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

# トークン移行ツールのログの読み方

> トークン移行ツールが初期化、移行対象クライアントの決定、トークン移行、シャットダウンの各フェーズで出力するログの内容と、ログに問題が示されている場合の確認点を説明します。

トークン移行ツール（Token Migrator）は、セルフマネージド環境で Authlete 2.3 から 3.0 へトークンを移行するために、Helm チャートでデプロイするツールです。導入手順は「[Kubernetes インストールガイド](/ja/deployment-and-operations/self-managed-deployment/kubernetes-installation-guide#移行フェーズ（任意）)」の「移行フェーズ（任意）」を参照してください。

トークン移行ツールは、複数のフェーズに分けて処理を実行します。本記事では、`token-migrator` コンテナが出力するログを、初期化、移行対象クライアントの決定、トークン移行のイテレーション、シャットダウンの各フェーズに分類し、各ログが示す内容と、ログに問題が示されている場合の確認点を説明します。

本記事は、トークン移行ツールのバージョン `1.4` のログにもとづいています。クラスの行番号はメッセージの文言よりもバージョン間で変わりやすいため、ログを検索する際は行番号ではなくメッセージの文言で検索してください（例: `ArgsUtils:113` ではなく `No batch size provided` で検索します）。

## 初期化

### 引数の解析

引数の解析時のログは、有効な各引数とオプションの値を示します。値が指定されていない場合や、指定された値が不正な場合は、代わりに使用されるデフォルト値が `WARN` 行に出力されます。

```text theme={null}
WARN [main] com.authlete.token.migrator.config.TokenMigratorConfig:59 - Invalid model version: [], detected database version [V2]
INFO [main] com.authlete.token.migrator.config.TokenMigratorConfig:62 - Using source model version: [V2]
...
INFO [main] com.authlete.token.migrator.etl.audit.AuditLogger:61 - Detected timestamp difference between local time and destination database time: [0]ms
INFO [main] org.springframework.boot.StartupInfoLogger:59 - Started TokenMigratorApplication in 12.499 seconds (process running for 13.802)
...
WARN [main] com.authlete.token.migrator.util.ArgsUtils:113 - No batch size provided, using [10000].
INFO [main] com.authlete.token.migrator.util.ArgsUtils:188 - Using batch-size [10000]
WARN [main] com.authlete.token.migrator.util.ArgsUtils:68 - No poll-interval provided, using 10000ms.
INFO [main] com.authlete.token.migrator.util.ArgsUtils:191 - Using poll-interval 10000ms.
WARN [main] com.authlete.token.migrator.util.ArgsUtils:57 - Failed to create migration directory, using default directory path /mapping-output
INFO [main] com.authlete.token.migrator.util.ArgsUtils:194 - Writing migration configuration output files to folder [/migrator/./mapping-output]
INFO [main] com.authlete.token.migrator.util.ArgsUtils:198 - No client IDs specified via the command line. In scope client's IDs will be determined by any common clients with the same client ID in the source and destination databases.
WARN [main] com.authlete.token.migrator.util.ArgsUtils:91 - No timestamp provided, using 0.
INFO [main] com.authlete.token.migrator.util.ArgsUtils:205 - Retrieving token creation and update events after timestamp: [0] as date: [1970-01-01 00:00:00.0]
WARN [main] com.authlete.token.migrator.util.ArgsUtils:162 - No audit log period provided, using [4].
INFO [main] com.authlete.token.migrator.util.ArgsUtils:213 - Using audit log period [4] hours.
...
INFO [main] com.authlete.token.migrator.tasks.MigrationTask:115 - Detected timestamp difference between local time and source database time: [0]ms
```

### 資格情報によるクライアントの解決（監査ログ用クライアント）

トークン移行ツールは、クライアントの資格情報を使用して、移行先の Authlete 3.0 環境にアクセスできることを確認します。資格情報の確認結果によって、トークン移行を実行するかどうかが決まります。トークン移行ツールは、資格情報が有効な間に限りトークンを移行します。初期化時、トークン移行ツールはクライアントクレデンシャルズグラントを使用して、移行先の Authlete 3.0 サーバーの Process Token Request API を呼び出します。アクセストークンを取得できた場合、トークン移行ツールは初期化を続行します。取得できなかった場合、トークン移行ツールは停止します。

トークン移行ツールは、設定された資格情報から特定されるクライアントを、監査ログイベントの作成にも使用します。トークン移行ツールによるトークンの変更は、監査ログ上ですべて監査ログ用クライアントに紐付けられます。

アクセストークンを取得できた場合、起動時に次のログが出力されます。

```text theme={null}
INFO [main] com.authlete.token.migrator.auth.CredentialValidator:95 - Resolved client credentials to client id: [<client-id>] in service with number [<service-number>].
INFO [main] com.authlete.token.migrator.TokenMigratorApplication:67 - Provided client credentials were used to successfully retrieve an access token from [https://<api-host>/api/<service-id>/auth/token]
```

以降の例では、各ログ行のメッセージ部分のみを示します。

必須の資格情報プロパティが設定されていない場合、次のエラーが出力されます。

* `token_request_url`（Helm チャートにより自動的に設定されます）:

  ```text theme={null}
  No `token_request_url` provided
  ```

* `service_token`（`authlete-credentials-secret.yml` シークレットの `tokenmigrator.serviceToken` で設定します）:

  ```text theme={null}
  No `service_token` provided
  ```

クライアントの資格情報を検証できない場合、次のいずれかのエラーが理由とともに出力されます。移行先環境のクライアント設定と、トークン移行ツールに指定した資格情報を確認してください。出力されるメッセージはエラーの内容によって異なります。

一般的なエラー（より詳細なエラーメッセージとともに出力されます）:

```text theme={null}
Retrieved access token is null from access token retrieval endpoint.
```

`authlete-credentials-secret.yml` シークレットの `tokenmigrator.serviceApiKey` で指定したサービスが、移行先データベースに存在しない場合:

```text theme={null}
Expected service with api key [<service-id>] to exist in destination database, but it does not.
```

設定されたエイリアスを持つクライアントが存在しない場合（エイリアスは `migration-service@system.authlete.com` であることが想定されており、Helm チャートでは変更できません）:

```text theme={null}
Expected client with client alias: [<alias>] to exist in destination database, but it does not.
```

Process Token Request API が 200 以外の HTTP ステータスを返した場合:

```text theme={null}
Failed to retrieve access token, received status code [<status-code>] and response [<response-body>]
```

Process Token Request API のレスポンスに `accessToken` プロパティが含まれていない場合:

```text theme={null}
Failed to retrieve access token, response body did not contain 'accessToken' property. Response [<response-body>]
```

### ドライランモードの表示

トークン移行ツールをドライランモード（`values.yaml` の `tokenmigrator.mode: dryrun`）で実行すると、トークンは書き込まれません。初期化時には、ドライランが有効であることを示す次のログが出力されます。

```text theme={null}
Skipping access token updates because the dry run flag is enabled.
```

### 処理完了時点のタイムスタンプの確認

トークン移行ツールを再起動して前回の続きから処理を再開する場合、0 以外の処理完了時点のタイムスタンプがログに出力されます（ログ上の表記は `moving timestamp` です）。処理完了時点のタイムスタンプは、トークン移行ツールが最後に保存した復旧ポイントです。トークン移行ツールは、復旧ポイント以降のトークン変更を検索します。詳細は「[トークン移行ツールの停止と再開](/ja/deployment-and-operations/self-managed-deployment/token-migrator/stopping-and-resuming-token-migrator)」を参照してください。

```text theme={null}
INFO [main] com.authlete.token.migrator.tasks.SyncTask:185 - Read in moving timestamp initial value [1784401524667]ms
```

`timestamp.txt` を読み込めなかった場合は、`Read in moving timestamp initial value` の代わりに次のログが出力されます。トークン移行ツールは、引数で指定された初期値（指定がない場合は `0`）から処理を開始します。

```text theme={null}
INFO [main] com.authlete.token.migrator.tasks.SyncTask:199 - Setting moving timestamp to the provided initial timestamp [0]ms
```

***

## 移行対象クライアントの決定

初期化に成功すると、トークン移行ツールは移行フェーズに移り、まず移行対象となるクライアントを決定します。トークン移行ツールは、新たに検出して移行対象に追加したクライアントを、それぞれログに出力します。移行対象クライアントのトークンは、作成または更新されるたびに確認され、移行されます。

トークン移行ツールは、クライアントが移行対象から除外された場合もログに出力します。

各クライアントは `<サービス ID>:<クライアント ID>` の形式で識別されます（例: `170886802516:143761865171655`）。

### クライアントとサービスの初期状態

移行フェーズの開始時に、現在のサービスとクライアントの状態が一度だけ出力されます。

```text theme={null}
INFO [main] com.authlete.token.migrator.etl.processor.ServiceAndClientMapper:65 - Initializing Client and Service ID mapping...
INFO [main] com.authlete.token.migrator.etl.processor.ServiceAndClientMapper:129 - Found [58166] clients in source database
INFO [main] com.authlete.token.migrator.etl.processor.ServiceAndClientMapper:137 - Found [50578] in-scope clients in destination database
INFO [main] com.authlete.token.migrator.etl.processor.ServiceAndClientMapper:171 - Found [30] services in source database
INFO [main] com.authlete.token.migrator.etl.processor.ServiceAndClientMapper:187 - Found [32] services in destination database
```

### 移行対象に追加されたクライアント

クライアントが移行対象に追加されると、次のログが出力されます。ログには、トークンを移行する対象となるすべてのクライアントの識別子が含まれます。

```text theme={null}
INFO [main] com.authlete.token.migrator.tasks.MigrationTask:144 - Found [2] new client IDs to add to migration scope [170886802516:143761865171655, 202488662850:518982711477060]
```

<Note>本メッセージには、トークン移行ツールが移行対象とするすべてのクライアントが列挙されるため、移行対象のクライアントの確認に利用できます。移行対象のクライアントが多い場合、メッセージが長くなることがあります。</Note>

### 移行対象から除外されたクライアント

クライアントが移行対象から除外されると、同様のメッセージが出力されます。

```text theme={null}
Removed [2] client(s) from scope [170886802516:143761865171655, 202488662850:518982711477060]
```

### クライアントシークレットの不一致

クライアントが移行対象に追加されるのは、クライアントシークレットが移行元と移行先のデータベースで同一の場合に限られます。

ほかのすべての条件を満たしているにもかかわらず、クライアントシークレットの不一致のみを理由に除外されたクライアントがある場合、次の警告が出力されます。

```text theme={null}
WARN [main] com.authlete.token.migrator.util.InScopeClientProvider:120 - Client [49864508303:9419823106018] exists in both database, but is not included in-scope because its client secret does not match.
```

警告に出力されたクライアントのトークンは移行されません。警告が出力されている場合は、該当するクライアントについて、移行先のクライアントシークレットを移行元の値に合わせて更新してください。更新には、クライアントシークレットの移行を有効にして[サービスとクライアントの移行スクリプト](/ja/deployment-and-operations/migration-from-existing-system/migrating-settings-from-an-older-version-of-authlete)を再実行するか、[Update Client Secret](/api-reference/client-management/update-client-secret) API を使用します。すべてのクライアントについて警告が出力されている場合は、クライアントのインポートまたは作成の処理が、移行先のクライアントを作成する際にクライアントシークレットの値を引き継いでいるかを確認してください。

クライアントが満たす必要のある条件の一覧は、「[クライアントトークンの移行条件](/ja/deployment-and-operations/migration-from-existing-system/migrating-settings-from-an-older-version-of-authlete#クライアントトークンの移行条件)」を参照してください。

***

## トークン移行のイテレーション

次に、トークン移行ツールは、各移行対象クライアントのトークンを取得し、移行先データベースにコピーします。

### 検出されたトークン

トークン移行ツールは、クライアントごとに、検出して移行するトークンの数と、検索した期間をログに出力します。

```text theme={null}
INFO [main] com.authlete.token.migrator.tasks.MigrationTask:221 - Found [150000] active token(s) for client with ID [49864508303:9184996925979] which have been created or modified after [2026-07-02 02:02:34.0] (1782957754000ms) and before [2026-07-02 02:02:53.0] (1782957773000ms)
```

### トークンの移行

トークンのバッチを書き込むたびに、書き込んだトークンのうち、更新されたトークンの数と新規作成されたトークンの数を示す次のログが出力されます。

```text theme={null}
INFO [main] com.authlete.token.migrator.etl.writer.AccessTokenItemWriter:78 - Wrote batch of [10000] token(s) for client ID [49864508303:9184996925979]. [10000] were updated, and [0] were created.
```

検索した期間内に作成または更新されたクライアントのトークンがすべて移行されると、所要時間、クライアント、書き込んだトークンの数、検索した期間を示す次のログが出力されます。

```text theme={null}
INFO [main] com.authlete.token.migrator.tasks.MigrationTask:280 - Migrated [150000] token(s) in 531978ms for client with ID [49864508303:9184996925979] which have been created or modified after [2026-07-02 02:02:34.0] (1782957754000ms) and before [2026-07-02 02:02:53.0] (1782957773000ms)
```

***

## シャットダウン時のログ

コンテナが停止されると、トークン移行ツールはシャットダウン中に、処理完了時点のタイムスタンプの最新値をログに出力します。永続ボリューム上の `timestamp.txt` が失われた場合は、ログに出力された値を使用して、処理を再開する時点を復元できます（「[トークン移行ツールの停止と再開](/ja/deployment-and-operations/self-managed-deployment/token-migrator/stopping-and-resuming-token-migrator)」を参照）。

```text theme={null}
INFO [Thread-1] com.authlete.token.migrator.tasks.SyncTask:92 - Shutting down sync migration task, latest timestamp [1784401524667]ms
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.