> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# データプライバシーとテレメトリ

ドキュメントはローカルで処理され、ABBYY をはじめとする第三者に送信されることは一切ありません。このページでは、コンテナーの外部に送信される情報、各 field に含まれる内容の詳細、およびそのストリームをご自身で確認またはコピーする方法について説明します。

<h2 id="what-fineparser-sends-to-abbyy">
  FineParser が ABBYY に送信する情報
</h2>

* **License の検証。** ドキュメントの処理時に、FineParser はアカウントに残っているページ残高を確認し、解析したページ数を差し引きます。これが課金記録となります。差し引き処理が完了しない場合、結果は保留されます。
* **テレメトリ。** FineParser はジョブごとに 1 つのトレース span と 1 組のメトリクス記録を送信します。これにより ABBYY は使用状況をお客様のアカウントに紐付け、製品の利用状況を把握できます。テレメトリは利用状況を示すシグナルであり、課金の仕組みではありません。また、リリースビルドでは常に有効です。

テレメトリの送信先に到達できない場合、設定が不正な場合、あるいはネットワークがまったく利用できない場合、FineParser はログに 1 行だけ記録し、そのプロセスではテレメトリを無効にしたまま処理を続行します。

<h2 id="what-telemetry-contains">
  テレメトリに含まれる内容
</h2>

FineParser は [OpenTelemetry](https://opentelemetry.io/) を使用し、2 種類のシグナルを出力します。1 つは、集計されたカウントとヒストグラムからなるメトリクスです。もう 1 つは、job ごとに 1 つの span を持つトレースです。いずれも、同じ少数の 属性 を使用します。

<h3 id="attributes-on-every-signal">
  すべてのシグナルに付与される属性
</h3>

これらの値はコンテナーの起動時に確定し、コンテナーが出力するすべてのシグナルに付与されます。

| 属性                     | 値                                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `service.name`         | 常に `fineparser` です。                                                                                                               |
| `service.version`      | コンテナーのビルドバージョンです。                                                                                                                 |
| `revenera.license_key` | お使いの License Key の GUID です。1 つのアカウントの使用状況が複数の値に分散しないよう、小文字化と正規化が行われます。License がない場合は、この属性自体が省略されます。                               |
| `languages`            | コンテナーの起動時に指定された recognition languages です。recognition engine に渡される値と同じものが使用されます。小文字化、重複排除、並べ替えが行われ、1 件あたり 32 文字、最大 16 エントリに制限されます。 |

<h3 id="per-job-attributes">
  ジョブ単位の属性
</h3>

ジョブ単位の属性はいずれも、あらかじめ定められた許可値の集合から選ばれます。集合に含まれない値は送出されずに破棄されるため、呼び出し側コードの不具合によって任意の文字列がシグナルに載ることはありません。

| 属性                | 許可値                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| `outcome`         | `ok`、`denied`、`error`、`rejected`                                                                                    |
| `mode`            | `accurate`、`fast`。[認識モード](/ja/fine-parser/basics/recognition-modes)を参照してください。                                       |
| `doc_type`        | `pdf`、`tiff`、`png`、`jpeg`、`other`                                                                                   |
| `output_type`     | `doclang`、`txt`、`json`。[出力形式](/ja/fine-parser/basics/output-formats)を参照してください。                                      |
| `decision`        | ジョブに対するライセンス判定: `ok`、`out_of_credits`、`rate_limited`、`not_provisioned`、`no_instance`、`server_unreachable`、`unknown` |
| `op`              | 計測対象のライセンス操作: `preview`、`debit`、`refund`                                                                            |
| `unbilled_reason` | `server_fault` または `not_found`。後述の[未課金ページ](#unbilled-pages)を参照してください。                                               |
| `correlation_id`  | ジョブごとに生成されるランダムなUUID。お客様やドキュメントに関する情報から導出されるものではありません。                                                              |
| `pages`           | 整数のページ数。ジョブのspanにのみ付与され、メトリクスのディメンションとして使われることはありません。                                                               |

`outcome` が `rejected` の場合は、処理が一切行われる前にリクエストが拒否されたことを意味します。たとえば、ファイルがアタッチされていない、出力形式がサポートされていない、アップロードが不正である、といった場合です。これを `error` と区別しているのは、クライアント側のAPIの誤用がFineParserの障害として扱われないようにするためです。

`decision` が `unknown` の場合は、ライセンスサーバーがコンテナーの認識できないステータスを返したことを意味します。この場合、FineParserはジョブを拒否します。既定で拒否することが本製品の方針であり、その判定は破棄されるのではなく報告されます。

<h3 id="metrics">
  メトリクス
</h3>

| インストゥルメント                      | 型         | 単位        | ディメンション                                      |
| ------------------------------ | --------- | --------- | -------------------------------------------- |
| `fineparser.jobs`              | Counter   | jobs      | `outcome`, `mode`, `doc_type`, `output_type` |
| `fineparser.pages`             | Counter   | pages     | `doc_type`, `mode`                           |
| `fineparser.pages.per_job`     | Histogram | pages     | `doc_type`, `mode`                           |
| `fineparser.job.duration`      | Histogram | ms        | `mode`                                       |
| `fineparser.meter.decisions`   | Counter   | decisions | `decision`                                   |
| `fineparser.meter.op.duration` | Histogram | ms        | `op`                                         |
| `fineparser.pages.unbilled`    | Counter   | pages     | `unbilled_reason`                            |

License Key は、各メトリクスの記録に加えてコンテナーレベルの属性にもアタッチされます。そのため、下流のバックエンドがリソース属性をどのようにマッピングするかにかかわらず、使用状況を License 単位でグループ化できます。

<h3 id="traces">
  トレース
</h3>

| Span            | 種類       | 保持する情報                                          |
| --------------- | -------- | ----------------------------------------------- |
| `job`           | Server   | 上記のジョブ単位の 属性 すべてに加え、`pages` と `correlation_id`。 |
| `meter.preview` | Internal | licensing の preview 呼び出しの所要時間。                  |
| `meter.debit`   | Internal | licensing の課金 (debit) 呼び出しの所要時間。                |
| `meter.refund`  | Internal | licensing の返金 (refund) 呼び出しの所要時間。               |

job span のステータスがエラーになるのは、結果が `error` の場合のみです。

<h2 id="what-fineparser-never-collects">
  FineParser が収集しないもの
</h2>

FineParser は、ドキュメントの内容、認識されたテキスト、ファイル名、ファイルパス、ファイルサイズ、顧客名、メールアドレス、アカウント識別子、ユーザー ID、IP アドレスを一切収集しません。

ファイル名がテレメトリモジュールに渡る経路は、ただ 1 つの function に限られます。この function は拡張子だけを読み取って `doc_type` の分類を返し、それ以外はすべて破棄します。FineParser のテストスイートには不正入力のテストがあり、人名、社会保障番号 (SSN) 形式の文字列、メールアドレス、一時パスをモジュールに渡したうえで、そのいずれもシンクに到達しないことを検証します。

License Key は、アカウントに意図的に紐付けられる唯一の値です。`languages` 属性は顧客データではなく deployment の設定であり、起動時に固定され、コンテナーが処理するすべての job で同一です。

このモジュールが送出できるのは、このページに記載された 11 個の属性キーのみです。任意の属性マップを受け取るエクスポート済みの function は存在しないため、field を追加するには許可リストのコードを変更する必要があります。

<h2 id="inspecting-and-copying-the-stream">
  ストリームの確認とコピー
</h2>

このページの記述を鵜呑みにする必要はありません。2つの環境変数でストリームを実際に確認でき、3つの環境変数でそのコピーを任意の宛先に送信できます。

| 変数                               | 効果                                                   |
| -------------------------------- | ---------------------------------------------------- |
| `FINEPARSER_TELEMETRY_STDOUT=on` | ストリームをそのままコンテナーのコンソールに出力します。                         |
| `FINEPARSER_OTLP_ENDPOINT`       | 指定したOTLPエンドポイント (自社のコレクターなど) に、同一内容のストリームのコピーを送信します。 |
| `FINEPARSER_OTLP_PROTOCOL`       | そのエンドポイントで使用するOTLPプロトコルです。                           |
| `FINEPARSER_OTLP_HEADERS`        | そのエンドポイントに付与するヘッダーです (認証トークンなど) 。                    |
| `FINEPARSER_TELEMETRY=off`       | リリースビルドでは受け付けられません。テレメトリを無効化することはできません。              |

送信先は追加できますが、削除はできません。お客様のエンドポイントとABBYYのエンドポイントは同一のストリームを受信します。これは方針ではなく、コードの構造そのものによって担保されています。テレメトリモジュールのどこにも、ABBYY専用の属性や2つ目のコードパスは存在しません。標準出力やお客様自身のコレクターで見える内容が、そのままABBYYが受け取る内容です。

FineParserはPrometheusのスクレイプエンドポイントを公開せず、OpenTelemetryのログシグナルも出力しません。ジョブ単位のイベントは、代わりにスパン属性として伝達されます。

<h2 id="unbilled-pages">
  未課金ページ
</h2>

`fineparser.pages.unbilled` カウンターは、課金が確定しないまま提供されたページを記録します。これが発生するのは、処理完了後にライセンスサーバーが 5xx エラーまたは 404 を返した場合のみで、このとき FineParser は完成した結果を保留せずに引き渡します。タイムアウトや証明書エラーの場合は結果自体がブロックされるため、このカウンターが支払いの回避を示すことはありません。値がゼロを上回っているのは、ライセンスベンダー側に不調があったことを意味し、利用者側に問題があったわけではありません。

<h2 id="known-limitations">
  既知の制限事項
</h2>

job を処理してから約 1 分以内に停止されたコンテナーでは、その job のテレメトリが失われます。これは、エクスポーターのシャットダウン時に最後の HTTP レスポンスを待機しないためです。長時間稼働するコンテナーの場合はすべて送信されます。License の計測には影響がなく、引き続き課金の記録として使用されるため、早期に停止した場合の影響は、ABBYY の使用状況ダッシュボードでの集計がわずかに少なくなる点のみです。

<h2 id="network-requirements">
  ネットワーク要件
</h2>

コンテナーは、ABBYY のライセンス管理基盤に常時接続できる必要があります。ファイアウォールまたは送信プロキシで、次の 2 つの範囲への送信トラフィックを許可してください。

| プロトコル | アドレス範囲               |
| ----- | -------------------- |
| IPv4  | `185.146.155.0/24`   |
| IPv6  | `2620:122:f003::/48` |

<Warning>
  FineParser がこれらのアドレスに到達できない場合、ドキュメントは一切解析されません。接続が回復するまで `/parse` へのリクエストは失敗します。送信接続のない環境については、[FineParser Enterprise](/ja/fine-parser/reference/enterprise) を参照してください。
</Warning>

この接続を経由するのは、ライセンス検証とテレメトリのみです。ドキュメントの内容が送信されることはありません。