データ転送¶
長期間保存する必要があるものの更新頻度が低いデータ(ログなど)は、データ転送機能によりオブジェクトストレージへ自動保存したり、Kafka などの外部システムへリアルタイム転送したりできます。この機能はルールに基づいてユーザーが必要とするデータを絞り込み、低コストで長期アーカイブを実現するとともに、後続の二次加工処理もサポートします。
ルールの有効化後、データ転送ページで検索期間とルールを設定すると、再検索をサポートする転送先で処理が完了したデータを検索できます。検索可能な期間は転送先のデータ処理サイクルによって異なります。
データ転送はメトリクスデータソースにも対応しています。ルールの新規作成時または編集時にメトリクスを選択し、フィルター条件を設定して、ルールに一致するメトリクスデータを外部サービスへ転送できます。具体的な操作については転送ルールを定義するを参照してください。
ローカルまたは自社のクラウド環境でデータを保持する必要がある場合は、LogBamboo を転送先として選択し、コンソールから履歴を検索できます。
機能の仕組み¶
LogBamboo を使用する場合は、LogBamboo へのデータ転送を参照してください。
JSON 形式でオブジェクトストレージへ転送する場合を例にすると、そのワークフローは次のとおりです。ルールに一致するユーザーから送信されたデータは、まず行単位でサーバーのローカルディスク上の一時ファイルに書き込まれます。この一時ファイルのサイズが累積で事前設定値(例:256MB)に達するか、継続書き込み時間が設定時間(例:1 時間)を超えると、システムは現在のファイルを自動的にクローズし、新しい一時ファイルを作成してデータの受信を続けます。
同時に、バックグラウンドサービスがこれらのクローズ済み一時ファイルを継続的にスキャンし、サイズを削減するために gzip 形式で圧縮した後、事前に定義されたパスルールに従って指定のオブジェクトストレージの場所へアップロードします。保存されたデータを検索する必要がある場合、システムは同じパスルールに基づいてオブジェクトストレージ内の関連ファイルを特定し、ダウンロードして解凍し、入力した検索条件と行単位で照合します。
ファイル形式の説明¶
JSON 保存形式を選択した場合、通常のアーカイブは gzip で圧縮されます。解凍後、ファイルの内容は複数行のテキストになり、各行が 1 件の元データレコードに対応し、データは JSON 形式で完全に保存されます。ファイル内の空行はシステムによって自動的に無視されます。
Parquet 保存形式を選択した場合、ファイルは Parquet 内部の GZIP で圧縮されるため、通常の gzip ファイルとして解凍できません。オブジェクトストレージルールで暗号化ストレージが有効になっている場合、ダウンロードしたアーカイブは先に復号する必要があります。
典型的なログタイプのデータ転送ファイルは次のようになります。
このうち date は必須フィールドで、該当データの時刻を識別するためのミリ秒単位の Unix タイムスタンプです。message フィールドは具体的なログ内容です。
{"__docid":"L_1750649205520_d1cciupkac7k1683bhq0","__namespace":"backup_log","date":1750649205520,"date_ns":168000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/gin.log","host":"X.local","log_read_lines":2,"message":"[GIN] 2025/06/23 - 11:26:43 | 200 | 1.012923708s | 127.0.0.1 | GET \"/metrics\"","message_length":87,"service":"default","source":"default","status":"unknown"}
{"__docid":"L_1750649205516_d1cciupkac7k1683bhqg","__namespace":"backup_log","date":1750649205516,"date_ns":897000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/gin.log","host":"X.local","log_read_lines":1,"message":"[GIN] 2025/06/23 - 11:26:38 | 200 | 1.012696542s | 127.0.0.1 | GET \"/metrics\"","message_length":87,"service":"default","source":"default","status":"unknown"}
{"__docid":"L_1750649206520_d1cciupkac7k1683bhr0","__namespace":"backup_log","date":1750649206520,"date_ns":948000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":150,"message":"2025-06-23T11:26:46.520+0800\tWARN\thost_processes\tprocess/input.go:332\tprocess: {\"pid\":411}, proc.PageFaults(): not implemented yet","message_length":130,"service":"default","source":"default","status":"unknown"}
{"__docid":"L_1750649205520_d1cciupkac7k1683bhrg","__namespace":"backup_log","date":1750649205520,"date_ns":419000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":9,"message":"2025-06-23T11:26:43.876+0800\tWARN\tcontainer\tcontainer/impl.go:254\tendpoint unix:///var/run/crio/crio.sock does not exist, maybe it is not running, skip","message_length":151,"service":"default","source":"default","status":"unknown"}
{"__docid":"L_1750649205517_d1cciupkac7k1683bhs0","__namespace":"backup_log","date":1750649205517,"date_ns":79000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":1,"message":"2025-06-23T11:26:38.365+0800\tWARN\thttp\thttpapi/http.go:494\tlistener.Close failed: close tcp [::]:9529: use of closed network connection","message_length":135,"service":"default","source":"default","status":"unknown"}
{"__docid":"L_1750649205517_d1cciupkac7k1683bhsg","__namespace":"backup_log","date":1750649205517,"date_ns":80000,"df_metering_size":-9223372036854775808,"filepath":"/var/log/datakit/log","host":"X.local","log_read_lines":2,"message":"2025-06-23T11:26:38.365+0800\tWARN\thttp\thttpapi/http.go:494\tlistener.Close failed: close tcp [::]:9529: use of closed network connection","message_length":135,"service":"default","source":"default","status":"unknown"}
ファイル命名と保存パス¶
[{$path_prefix}/]{$workspace_uuid}/[{$data_type}/]
{$rule_name}/{$year}/{$month}/{$day}/{$hour}/{$time}-{$hostname}.gz
[] で囲まれた部分は「オプション項目」を表します。詳細は以下の説明を参照してください。
変数 |
説明 |
例 | 備考 |
|---|---|---|---|
$path_prefix |
パスプレフィックス | path/to/backup |
オプション。新しいバックアップルール作成時の保存パスオプションに対応します オブジェクトストレージは / で始まるキーをサポートしていないため、/ で始めないでください |
$workspace_uuid |
ワークスペース ID | wksp_d9a1851859e040469d290409bc17cceb |
|
$data_type |
バックアップデータタイプ。指定可能な値:logging:ログrum:リアルユーザーモニタリング(RUM)tracing:トレーシングevent:イベントaudit_event:監査イベント |
tracing |
ログはデフォルトのデータタイプであるため、ログタイプのデータでは {$data_type}/(つまり logging/)部分を省略する必要があります |
$rule_name |
ルール名 | backup_logging_for_test |
新しいルール作成時のルール名オプションに対応します 英語の使用を推奨します |
$year |
ログ発生日時の年(4 桁) | 2025 |
UTC タイムゾーン |
$month |
ログ発生日時の月(2 桁) | 03 |
UTC タイムゾーン |
$day |
ログ発生日時の日(2 桁) | 01 |
UTC タイムゾーン |
$hour |
ログ発生日時の時(2 桁) | 22 |
UTC タイムゾーン |
$time |
ファイル内の最後のログの発生時刻 形式:時時分分秒秒 + 3 桁のミリ秒 |
220607889 |
UTC タイムゾーン |
$hostname |
ホスト名を MD5 で計算した後、先頭 16 桁を取得 | c6a92aafa992599c |
独自にファイルを構築する場合は、現在のファイルの crc64 を使用できます または 64 ビットの乱数をランダム生成して 16 進数に変換します |
パスの例:
wksp_d9a1851859e040469d290409bc17cceb/backup_logging_for_test/2025/05/06/17/175950000-c6a92aafa992599c.gz
path/to/backup/wksp_d9a1851859e040469d290409bc17cceb/tracing/test-minio/2025/05/06/17/175950000-c6a92aafa992599c.gz
ファイル分割ルール
- 時間境界:1 つのファイルには同一時間内のログのみが含まれ、時間をまたぐことはありません
- サイズ境界:非圧縮の元ファイルは 256 MB~512 MB に収めます。gzip 圧縮後は通常数十 MB~100 MB 程度になります。大きすぎても小さすぎても検索効率が低下します
外部ファイルをデータ転送ルールが生成する形式とパスルールに従ってオブジェクトストレージへアップロードできます。コンソールは同じ方法で検索および表示を行います。
はじめに¶
転送ルールを作成¶
転送先の種類に応じて、業務要件に合ったデータ転送ルールを作成します。
| タイプ | 転送先 |
|---|---|
| 組み込みストレージ | Guance |
| オブジェクトストレージ | AWS S3、Huawei Cloud OBS、Alibaba Cloud OSS、Volcengine TOS、Google Cloud GCS |
| 分析プラットフォーム | Apache Doris、TiDB Cloud Lake、LogBamboo |
| メッセージキュー | Kafka |
転送ルールを管理¶
データ転送ルール一覧では、一連の操作によって管理できます。
データ閲覧権限¶
データ転送ルールの作成時に、ワークスペース内のすべてのメンバーにデータの閲覧を許可するか、データを閲覧できるメンバーロールを指定できます。具体的な設定についてはデータ閲覧権限を定義するを参照してください。
ファイルの復号¶
AWS S3、Huawei Cloud OBS、Alibaba Cloud OSS、Volcengine TOS、Google Cloud GCS への転送で、保存形式が JSON または Parquet であり、暗号化ストレージが有効なアーカイブファイルに適用されます。AWS S3 の Apache Iceberg 形式には適用されません。
| ファイル拡張子 | 処理方法 | 出力ファイル |
|---|---|---|
.lock.gz |
復号ツールで復号し、gzip 解凍を実行 | JSON 行ファイル(例:.jsonl) |
.parquet.lock.gz |
復号ツールで復号し、gzip 解凍は実行しない | .parquet |
.gz |
未暗号化。直接 gzip 解凍を実行 | JSON 行ファイル(例:.jsonl) |
.parquet.gz |
未暗号化。Parquet 読み取りツールで直接開く | Parquet ファイル |
準備¶
- オブジェクトストレージから完全なアーカイブファイルをダウンロードし、元のコピーを保持します。
- ワークスペース ID(UUID)を取得します。ファイルが属するワークスペースの管理 > ワークスペース設定 > 基本情報でコピーでき、
wksp_で始まる完全な値を使用します。 - 使用可能な Go 環境を準備し、復号ツール
decrypt.goをダウンロードします。ツールは Go 標準ライブラリのみに依存し、ローカルでファイルを処理するため、オブジェクトストレージのアクセスキーは不要です。
操作手順¶
以下のコマンドは macOS または Linux の Bash、Zsh に適用されます。ツールとアーカイブを同じディレクトリに置き、そのディレクトリでターミナルを開きます。実際のファイル名に合わせて -in と -out を変更し、-workspace の値を準備でコピーした完全なワークスペース ID に置き換えます。-out にはまだ存在しない出力パスを使用してください。
1. Go 環境を確認する¶
2. デフォルトの復号パラメータを使用する¶
ツールにはデフォルトの IV(初期化ベクトル。暗号化時に使用するパラメータの 1 つ)が組み込まれています。アーカイブがデフォルトの暗号化設定を使用している場合、IV を別途取得または入力する必要はありません。次のコマンドを実行し、ツールが組み込みのデフォルト値を使用するようにします。
デプロイ環境でカスタム暗号化パラメータを使用している場合
サーバー側で backup_log.iv が変更されている場合は、そのデプロイ環境の保守担当者に連絡し、ファイル生成時に使用された設定値を取得してください。その後、次のコマンドで上記の unset コマンドを置き換えます。
KODO_BACKUP_IV は、この値をローカルの復号ツールに渡すだけです。デフォルト値を使用することを示すために空文字列を設定しないでください。設定が変更された場合、古いファイルでは生成時の値を使用する必要があります。
3. 復号を実行する¶
ツールは復号後のファイルヘッダーに基づいて形式を識別し、ファイル名には依存しません。入力ファイルはそのまま保持されます。出力パスが既に存在する場合は上書きされず、処理に失敗した場合は今回生成された不完全な出力ファイルの削除を試みます。
4. 復号結果を確認する¶
コマンドが正常に終了すると、ターミナルはファイル形式に応じて対応するメッセージを出力します。
または:
- JSON 行ファイル:各行が JSON として解析できることを確認し、時刻やデータ内容などのフィールドを抜き取り確認します。
- Parquet ファイル:Parquet 読み取りツールで開き、スキーマとデータ内容を確認します。
gunzipは実行しないでください。
任意:コンパイル後に使用する¶
go build -o backup-decrypt decrypt.go
./backup-decrypt -in "./archive.lock.gz" -out "./archive.jsonl" -workspace "wksp_your_workspace_uuid"
コンパイル後のツールも KODO_BACKUP_IV を通じてカスタム IV を読み取ります。同じオペレーティングシステムとアーキテクチャのマシンにコピーして実行できます。ターゲットマシンに Go をインストールする必要はありません。
未暗号化ファイル¶
通常の .gz ファイルは直接解凍できます。出力ファイル名にはまだ存在しないパスを選択してください。
このコマンドは元のアーカイブを保持します。出力ファイルが既に存在する場合はエラーになり停止するため、ファイル名を変更してください。.parquet.gz は Parquet 内部の GZIP 圧縮を使用しているため、Parquet 読み取りツールに直接渡し、このコマンドは使用しません。
よくある質問¶
| 現象 | 確認と対処 |
|---|---|
unrecognized decrypted header |
wksp_ で始まる完全なワークスペース ID、ファイル生成時の IV、ファイルの整合性を確認してください。未暗号化ファイルは復号ツールで処理しないでください。 |
invalid gzip header または gzip 検証失敗 |
復号パラメータを確認し、元のアーカイブを再ダウンロードして、破損や切り詰めがないか確認してください。 |
Parquet に対して gunzip を実行するとエラー |
Parquet 読み取りツールで復号後のファイルを直接開いてください。 |
file exists |
まだ存在しない出力ファイル名に変更してください。 |
go: command not found |
Go をインストールするか、別のマシンでコンパイルして互換性のある実行ファイルをコピーしてください。 |
permission denied |
入力ファイルが読み取り可能で、出力ディレクトリが書き込み可能であることを確認してください。 |
no space left on device |
解凍後のデータ量に応じてディスク容量を確保してください。 |
no such file or directory |
ツールとアーカイブのパスを確認し、出力ディレクトリを事前に作成してください。 |