コンテンツにスキップ

データ転送


長期間保存する必要があるものの更新頻度が低いデータ(ログなど)は、データ転送機能によりオブジェクトストレージへ自動保存したり、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 ファイル

    準備

    1. オブジェクトストレージから完全なアーカイブファイルをダウンロードし、元のコピーを保持します。
    2. ワークスペース ID(UUID)を取得します。ファイルが属するワークスペースの管理 > ワークスペース設定 > 基本情報でコピーでき、wksp_ で始まる完全な値を使用します。
    3. 使用可能な Go 環境を準備し、復号ツール decrypt.go をダウンロードします。ツールは Go 標準ライブラリのみに依存し、ローカルでファイルを処理するため、オブジェクトストレージのアクセスキーは不要です。

    操作手順

    以下のコマンドは macOS または Linux の Bash、Zsh に適用されます。ツールとアーカイブを同じディレクトリに置き、そのディレクトリでターミナルを開きます。実際のファイル名に合わせて -in と -out を変更し、-workspace の値を準備でコピーした完全なワークスペース ID に置き換えます。-out にはまだ存在しない出力パスを使用してください。

    1. Go 環境を確認する

    go version
    

    2. デフォルトの復号パラメータを使用する

    ツールにはデフォルトの IV(初期化ベクトル。暗号化時に使用するパラメータの 1 つ)が組み込まれています。アーカイブがデフォルトの暗号化設定を使用している場合、IV を別途取得または入力する必要はありません。次のコマンドを実行し、ツールが組み込みのデフォルト値を使用するようにします。

    unset KODO_BACKUP_IV
    
    デプロイ環境でカスタム暗号化パラメータを使用している場合

    サーバー側で backup_log.iv が変更されている場合は、そのデプロイ環境の保守担当者に連絡し、ファイル生成時に使用された設定値を取得してください。その後、次のコマンドで上記の unset コマンドを置き換えます。

    export KODO_BACKUP_IV='文件生成时使用的 IV'
    

    KODO_BACKUP_IV は、この値をローカルの復号ツールに渡すだけです。デフォルト値を使用することを示すために空文字列を設定しないでください。設定が変更された場合、古いファイルでは生成時の値を使用する必要があります。

    3. 復号を実行する

    go run decrypt.go \
      -in "./archive.lock.gz" \
      -out "./archive.jsonl" \
      -workspace "wksp_your_workspace_uuid"
    

    ツールは復号と gzip 解凍を自動的に実行します。生成された .jsonl は行単位で JSON を読み取れるため、再度解凍する必要はありません。

    go run decrypt.go \
      -in "./archive.parquet.lock.gz" \
      -out "./archive.parquet" \
      -workspace "wksp_your_workspace_uuid"
    

    ツールは復号後に Parquet ファイルを生成します。Parquet 読み取りツールで直接スキーマとデータを確認してください。復号ツールは完全な Parquet 構造検証を実行しません。

    ツールは復号後のファイルヘッダーに基づいて形式を識別し、ファイル名には依存しません。入力ファイルはそのまま保持されます。出力パスが既に存在する場合は上書きされず、処理に失敗した場合は今回生成された不完全な出力ファイルの削除を試みます。

    4. 復号結果を確認する

    コマンドが正常に終了すると、ターミナルはファイル形式に応じて対応するメッセージを出力します。

    Restored decompressed JSON/NDJSON: ./archive.jsonl
    

    または:

    Restored Parquet: ./archive.parquet
    
    • 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 ファイルは直接解凍できます。出力ファイル名にはまだ存在しないパスを選択してください。

    (set -C; gzip -dc "./archive.gz" > "./archive.jsonl")
    

    このコマンドは元のアーカイブを保持します。出力ファイルが既に存在する場合はエラーになり停止するため、ファイル名を変更してください。.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 ツールとアーカイブのパスを確認し、出力ディレクトリを事前に作成してください。

    フィードバック

    このページは役に立ちましたか?