コンテンツにスキップ

Dataway


概要

DataWay はGuanceのデータゲートウェイです。コレクターがGuanceにデータを送信する際は、すべて DataWay ゲートウェイを経由する必要があります。

Dataway のインストール

  • Dataway を作成

Guanceの管理コンソールの「データゲートウェイ」ページで、「Dataway を作成」をクリックします。名前とバインドアドレスを入力した後、「作成」をクリックします。

作成に成功すると、新しい Dataway が自動的に作成され、Dataway のインストールスクリプトが生成されます。

Info

バインドアドレスは Dataway ゲートウェイのアドレスです。完全な HTTP アドレスを入力する必要があります。たとえば http(s)://1.2.3.4:9528 のように、プロトコル、ホストアドレス、ポートを含めます。ホストアドレスには通常、Dataway をデプロイするマシンの IP アドレスを使用できます。ドメイン名を指定することもでき、その場合は名前解決を設定しておく必要があります。

注意:コレクターがこのアドレスにアクセスできることを確認してください。アクセスできない場合、データ収集は成功しません。

  • Dataway をインストール
DW_KODO=http://kodo_ip:port \
   DW_TOKEN=<tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX> \
   DW_UUID=<YOUR_UUID> \
   bash -c "$(curl https://static.guance.com/dataway/install.sh)"

ホストへのインストールは推奨されません。Kubernetes StatefulSet を使用して Dataway をインストールしてください。

インストール完了後、インストールディレクトリに dataway.yaml が生成されます。内容の例は以下のとおりで、手動で変更し、サービスを再起動することで反映できます。

dataway.yaml(クリックして展開)
# ============= DATAWAY CONFIG =============

# Dataway UUID, we can get it on during create a new dataway
uuid:

# It's the workspace token, most of the time, it's
# system worker space's token.
token:

# secret_token used under sinker mode, and to check if incomming datakit
# requests are valid.
secret_token:

# If __internal__ token allowed? If ok, the data/request will direct to
# the workspace with the token above
enable_internal_token: false

# is empty token allowed? If ok, the data/request will direct to
# the workspace with the token above
enable_empty_token: false

# Is dataway cascaded? For cascaded Dataway, it's remote_host is
# another Dataway and not Kodo.
cascaded: false

# kodo(next dataway) related configures
remote_host:
http_timeout: 3s
# 受信 HTTP の期限。下流リクエストのタイムアウトとは独立
http_read_timeout: 5m
http_write_timeout: 10m
http_idle_timeout: 2m

http_max_idle_conn_perhost: 0 # default to CPU cores
http_max_conn_perhost: 0      # default no limit
kodo_queue:
  enabled: true
  # Body を読み取る前に処理が許可される HTTP 同時実行数も制限
  workers: 256
  queue_size: 1024
  queue_max_bytes: 1073741824 # 1GB
  enqueue_timeout: 100ms

insecure_skip_verify: false
http_client_trace: false
sni: ""

# dataway API configures
# IPv4 と IPv6 は独立した listener を使用し、OS の bindv6only 動作への依存を避ける
bind: 0.0.0.0:9528
# IPv6 はデフォルトで無効。必要な場合は明示的に "[::]:9528" を設定
bind_ipv6: ""

# 信頼済みプロキシからのリクエストのみ、転送ヘッダーを使用して IP ホワイトリスト判定を行う
# trusted_proxies:
#   - 10.0.0.0/8
#   - 2001:db8:ffff::/48

# disable 404 page
disable_404page: false

# dataway TLS file path
tls_crt:
tls_key:

# pprof はデフォルトで無効。設定できるのは loopback リスンアドレスのみ
pprof_bind: ""

api_limit_rate : 100000         # 100K
max_http_body_bytes : 67108864  # 64MB
copy_buffer_drop_size : 262144  # 256KB, if copy buffer memory larger than this, this memory released
reserved_pool_size: 4096        # reserved pool size for better GC

within_docker: false

log_level: info
log: log
gin_log: gin.log               # 空文字列に設定すると HTTP アクセスログを無効化

ip_black_list:
  ttl: "1m"
  clean_interval: "1h"

cache_cfg:
  # cache disk path
  dir: "disk_cache"

  # disable cache
  disabled: false

  clean_interval: "1s"

  # in MB, max single data package size in disk cache, such as HTTP body
  max_data_size: 100

  # in MB, single disk-batch(single file) size
  batch_size: 128

  # in MB, max disk size allowed to cache data
  max_disk_size: 65535

  # expire duration, default 7 days
  expire_duration: "168h"

prometheus:
  listen: "localhost:9090"
  url: "/metrics"
  enable: true

#sinker:
#  cache_options:
#    prealloc: true
#    reserved_capacity: 10000000 # max cached items
#    buckets: 64
#    ttl: 10m # clear unactive matches
#  etcd:
#    urls:
#    - http://localhost:2379 # one or multiple etcd host
#    dial_timeout: 30s
#    key_space: "/dw_sinker" # subscribe to the etcd key
#    username: "dataway"
#    password: "<PASSWORD>"
#  file:
#    path: /path/to/sinker.json

Dataway Pod の YAML は次のとおりです:

dataway-statefulset.yaml(クリックして展開)
---

apiVersion: apps/v1
kind: StatefulSet
metadata:
  labels:
    app: sts-utils-dataway
  name: dataway
  namespace: utils
spec:
  replicas: 2
  selector:
    matchLabels:
      app: sts-utils-dataway
  serviceName: dataway
  template:
    metadata:
      annotations:
        datakit/logs: |
          [
            {
              "disable": false,
              "source": "dataway",
              "service": "dataway",
              "multiline_match": "^\\d{4}|^\\[GIN\\]"
            }
          ]
        datakit/prom.instances: |
          [[inputs.prom]]
            url = "http://$IP:9090/metrics"

            source = "dataway"
            measurement_name = "dw"
            interval = "10s"
            disable_instance_tag = true
          [inputs.prom.tags]
            service = "dataway"
            instance = "$PODNAME" # we can set as "xxx-$PODNAME"
      labels:
        app: sts-utils-dataway
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchExpressions:
                  - key: app
                    operator: In
                    values:
                      - sts-utils-dataway
              topologyKey: kubernetes.io/hostname
      containers:
        - env:
            - name: DW_REMOTE_HOST
              value: http://kodo.forethought-kodo:9527
            - name: DW_BIND
              value: 0.0.0.0:9528
            # IPv6 をリッスンする場合は、次の 2 行のコメントを解除
            # - name: DW_BIND_IPV6
            #   value: "[::]:9528"
            - name: DW_UUID
              value: agnt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Dataway UUID
            - name: DW_TOKEN
              value: tkn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # Dataway token
            - name: DW_PROM_LISTEN
              value: 0.0.0.0:9090
            - name: DW_LOG
              value: stdout
            - name: DW_LOG_LEVEL
              value: info
            - name: DW_GIN_LOG
              value: stdout
            - name: DW_DISKCACHE_DIR
              value: cache
            - name: DW_HTTP_TIMEOUT
              value: '3s'
            - name: DW_ENABLE_INTERNAL_TOKEN
              value: 'false'
            - name: DW_MAX_HTTP_BODY_BYTES
              value: '67108864'
            - name: DW_HTTP_CLIENT_TRACE
              value: 'on'
            - name: DW_RESERVED_POOL_SIZE
              value: '0'
            - name: DW_COPY_BUFFER_DROP_SIZE
              value: '262144'
            - name: DW_DISKCACHE_CAPACITY_MB
              value: 102400
          image: pubrepo.guance.com/dataflux/dataway:1.22.2
          imagePullPolicy: IfNotPresent
          name: dataway
          ports:
            - containerPort: 9528
              name: 9528tcp01
              protocol: TCP
          resources:
            limits:
              cpu: '4'
              memory: 4Gi
            requests:
              cpu: 100m
              memory: 512Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
          volumeMounts:
            - mountPath: /usr/local/cloudcare/dataflux/dataway/cache
              name: dataway-cache
      dnsPolicy: ClusterFirst
      imagePullSecrets: []
      #nodeSelector:
      #  nodepool: dataway
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
      #tolerations:
      #  - effect: NoSchedule
      #    key: nodepool
      #    operator: Equal
      #    value: dataway
  updateStrategy:
    rollingUpdate:
      partition: 0
    type: RollingUpdate
  volumeClaimTemplates:
    - apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
        name: dataway-cache
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 100Gi
        storageClassName: xxxxxx  # High-Performance Storage StorageClass
        volumeMode: Filesystem
      status:
        phase: Pending

---

apiVersion: v1
kind: Service
metadata:
  name: dataway
  namespace: utils
spec:
  ipFamilyPolicy: SingleStack # デュアルスタックモードの場合は PreferDualStack に変更
  # ipFamilies:
  #   - IPv4
  #   - IPv6
  ports:
    - name: 9528tcp02
      nodePort: 30928
      port: 9528
      protocol: TCP
      targetPort: 9528
  selector:
    app: sts-utils-dataway
  type: NodePort

デフォルトの例では IPv4 シングルスタックを使用します。デュアルスタックを有効にする場合は、Kubernetes クラスタおよび CNI が IPv4/IPv6 デュアルスタックをサポートしていることを確認したうえで、以下の設定を同時に変更してください:

  1. Dataway コンテナの環境変数で DW_BIND_IPV6 のコメントを解除し、[::]:9528 に設定して、Dataway が IPv4 と IPv6 の両方をリッスンするようにします。
  2. Service の ipFamilyPolicy を SingleStack から PreferDualStack に変更し、ipFamilies 配下の IPv4、IPv6 のコメントを解除します。

これら 2 項目は同時に有効にする必要があります。Service のみを変更して DW_BIND_IPV6 を設定しない場合、Dataway は IPv6 リクエストを受信しません。

dataway-statefulset.yaml では、環境変数を通じて Dataway の設定を変更できます。詳細はこちらを参照してください。

ConfigMap で dataway.yaml を外部マウントすることもできますが、/usr/local/cloudcare/dataflux/dataway/dataway.yaml にマウントする必要があります:

containers:
  volumeMounts:
    - name: dataway-config
      mountPath: /usr/local/cloudcare/dataflux/dataway/dataway.yaml
      subPath: config.yaml
volumes:
- configMap:
    defaultMode: 256
    name: dataway-config
    optional: false
  name: dataway-config

コンテナインストールに必要な環境変数は Kubernetes と同一です。以下の Docker コマンドで DataWay コンテナを起動できます:

docker run -d \
    --name <YOUR-DW-IN-DOCKER> \
    -p 19528:9528 -p 19090:9090 \
    --mount type=bind,source=<host/path/for/diskcache>,target=/usr/local/cloudcare/dataflux/dataway/cache \
    --memory=2g --memory-reservation=256m \
    --cpus="2" \
    -e DW_UUID=<YOUR-AGNT_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX> \
    -e DW_TOKEN=<YOUR-TKN_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX> \
    -e DW_REMOTE_HOST=http://kodo.forethought-kodo:9527 \
    -e DW_BIND=0.0.0.0:9528 \
    -e DW_PROM_LISTEN=0.0.0.0:9090 \
    -e DW_HTTP_CLIENT_TRACE=true \
    -e DW_LOG_LEVEL=info \
    -e DW_LOG=stdout \
    -e DW_GIN_LOG=stdout \
    -e DW_DISKCACHE_CAPACITY_MB=65536 \
    pubrepo.guance.com/dataflux/dataway:1.22.2

注意事項
  • Dataway は Linux システム上でのみ実行できます(現在は Linux arm64/amd64 のバイナリのみ提供)
  • ホストインストールの場合、Dataway のインストールパスは /usr/local/cloudcare/dataflux/dataway です
  • Kubernetes ではデフォルトで 4000m/4Gi のリソース制限が設定されています。実際の状況に応じて調整してください。最小要件は 100m/512Mi です
  • Dataway のインストールを確認

インストール完了後、しばらく待って「データゲートウェイ」ページを更新します。先ほど追加したデータゲートウェイの「バージョン情報」列にバージョン番号が表示されていれば、この Dataway はGuanceセンターとの接続に成功しており、フロントエンドユーザーはこれを経由してデータを取り込めます。

Dataway がGuanceセンターとの接続に成功したら、Guanceコンソールにログインし、「インテグレーション」/「DataKit」ページで利用可能なすべての Dataway アドレスを確認します。必要な Dataway ゲートウェイアドレスを選択し、DataKit のインストールコマンドを取得してサーバー上で実行すると、データ収集を開始できます。

DataWay の管理

DataWay の削除

Guanceの管理コンソールの「データゲートウェイ」ページで、削除する DataWay を選択し、「設定」をクリックします。表示された DataWay 編集ダイアログで、左下の「削除」ボタンをクリックします。

Warning

DataWay を削除した後、DataWay ゲートウェイをデプロイしたサーバーにログインして DataWay の実行を停止し、インストールディレクトリを削除する必要があります。これにより DataWay を完全に削除できます。

DataWay のアップグレード

Guanceの管理コンソールの「データゲートウェイ」ページで、DataWay にアップグレード可能なバージョンがある場合、「バージョン情報」にアップグレードの通知が表示されます。

DW_UPGRADE=1 bash -c "$(curl https://static.guance.com/dataway/install.sh)"

イメージバージョンを置き換えるだけです:

- image: pubrepo.guance.com/dataflux/dataway:1.22.2

Dataway サービスの管理

ホストに Dataway をインストールした場合、以下のコマンドで Dataway サービスを管理できます。

# 起動
$ systemctl start dataway

# 再起動
$ systemctl restart dataway

# 停止
$ systemctl stop dataway

Kubernetes では、対応する Pod を再起動するだけです。

環境変数

イメージ環境変数

Dataway を Kubernetes 環境で実行する場合、以下の環境変数をサポートします。

既存の dataway.yaml との互換性

一部の古い Dataway では ConfigMap 方式で設定を注入しています(コンテナにマウントされるファイル名は通常 dataway.yaml です)。 Dataway イメージの起動後、インストールディレクトリに ConfigMap でマウントされたファイルが存在する場合、以下の DW_* 環境変数は有効になりません。 既存の ConfigMap マウントを削除した後、これらの環境変数が有効になります。

環境変数が有効な場合、Dataway のインストールディレクトリに隠しファイル(ls -a で確認).dataway.yaml が作成されます。cat でこのファイルを確認し、環境変数の反映状況を確認できます。

HTTP Server 設定

HTTP リクエストは Body を読み取る前に同時実行制限を行います。上限は kodo_queue.workers(環境変数 DW_KODO_QUEUE_WORKERS)を再利用し、デフォルトは 256 です。未設定または正数でない場合はデフォルト値を使用します。上限に達した後、最大で追加 128 個のリクエストを待機させ、最長 1s 待機します。待機期間中は Body を読み取りません。リクエスト処理が終了すると同時実行枠を解放します。待機枠が満杯またはタイムアウトした場合、登録済みの DK 互換インターフェースは 503 を返し、その他のインターフェースは 429 を返します。いずれも Retry-After: 1 を含み、これらのリクエストはディスクキャッシュに入りません。このステータスコードの区別は HTTP 同時実行の受け入れ拒否にのみ使用され、後続の転送およびキャッシュのエラーレスポンスを変更しません。Body を持つすべてのリクエストは同じ同時実行制限を共有し、Body のないリクエストはカウントされません。HTTP 同時実行制限は Kodo worker と設定値を共有しますが、特定の worker にバインドされません。Kodo ディスパッチキューを無効にしても、HTTP 同時実行制限は無効になりません。この制限は Pod の総メモリを保証するものではありません。

HTTP/1.x リクエストが同時実行制限で拒否された場合、Dataway は残りの Body の読み取りを終了し、レスポンスを返した後に接続を閉じます。クライアントがリトライする際は新しい接続を確立する必要があります。

受信 HTTP リクエストでは以下の期限を使用し、いずれも下流の http_timeout とは独立しています:

設定項目 デフォルト値 作用
http_read_timeout 5m Body 全体のアップロード時間を制限。HTTP/1.x ではリクエストヘッダーの読み取り時間も含み、少量のデータを送り続けても期限は延長されない
http_write_timeout 10m レスポンスの書き込み期限を制限。アップロード時間とリクエスト処理時間を含む
http_idle_timeout 2m 持続接続が次のリクエストを待つアイドル時間を制限

リクエストボディの読み取りタイムアウト時は、リトライ可能な 503(dataway.httpBodyReadTimeout)を返し、同時実行枠を解放し、完全に受信していないデータはキャッシュしません。ストリーミング転送では下流が一部のデータをすでに受信している可能性があるため、クライアントは引き続きリトライする必要があります。

リクエストヘッダーの読み取り期限は引き続き 10s です。書き込み期限は読み取り期限に想定処理時間を加えた値より大きくする必要があります。これらはすべてネットワークの読み取り/書き込み期限であり、CPU 計算を強制終了するものではありません。

RUM は最初のバイトを読み取る前にローカルで token 検証を実行します。token が欠落している場合、またはローカル設定で拒否された場合は、対応する認証エラーを直ちに返します。HTTP/1.x では残りの Body の読み取りを終了し、アップロードのタイムアウトを待たずに接続を閉じます。空の token、内部 token、および sink 以外のリクエストにおける secret token の互換ルールは変更されません。集約およびテールサンプリングの proxy モードでは、バックエンド接続に失敗した場合に 502(dataway.proxyFailed)を返します。バックエンドがすでに返したレスポンスは、空のレスポンスを含め、そのステータスコードを保持します。

3 つの設定はいずれも正数である必要があります。YAML で非正数の場合、および ENV で不正または非正数の場合は警告を出力してデフォルト期限を保持し、不正な YAML の期間は設定の読み込み失敗につながります。通常の大きなパケットや低速なネットワークでは、読み取り/書き込み期限を適切に大きくできます。まず実際のアップロード所要時間に基づいて調整することを推奨します。セマンティクスについては Go HTTP Server ドキュメントを参照してください。

DK 互換インターフェースは以下の一覧で照合し、token、query、User-Agent によってクライアントの身元を判断しません。第三者が同じインターフェースを呼び出した場合も 503 を受け取ります。DK インターフェースを追加する際は一覧も同期して保守する必要があり、すべての /v1/write/* を DK インターフェースと見なすことはできません。

503 を返すインターフェース種別 パス
DK データ書き込みカテゴリ /v1/write/{metric,metrics,network,keyevent,object,object_change,custom_object,logging,tracing,rum,security,profiling,dialtesting,siem_logging,langfuse-v2,agent_llm,dynamic_dw};cliutils/point のカテゴリ定義を再利用し、互換カテゴリと予約カテゴリを含む
DK 特殊書き込み /v1/write/{heartbeat,bugreport,remote_job,dialtesting_browser_screenshot}
リプレイとプロファイリング /v1/write/rum/replay、/v1/write/rum/replay_assets、/v1/check/rum/replay_assets、/v1/upload/profiling
集約とテールサンプリング /v1/aggregate、/v1/tail_sampling、/v1/tail_sampling_v2、/v1/tail_sampling_config、/v2/tail_sampling
OCSF 受信 /v1/ocsf_ingest
DK 制御インターフェース /v1/datakit/usage_trace、/v1/datakit/pull、/v1/election、/v1/election/heartbeat、/v1/query/raw、/v1/workspace、/v1/object/labels、/v1/check/token/:token、/v1/env_variable、/v1/ntp、/v1/ping

Cloudflare の /v1/write/cf-logpush、AWS Firehose の /v1/input/firehose、OTLP の /otel/v1/*、Langfuse の /api/public/*、およびその他一覧にないインターフェースは、受け入れ拒否時に 429 を返します。Body のないヘルスチェックや設定取得などのリクエストは引き続きそのまま許可されます。

Env 説明
DW_REMOTE_HOST
type: string
required: Y
Kodo アドレス、または次の Dataway アドレス。形式は http://host:port
DW_WHITE_LIST
type: string
required: N
Dataway クライアントの IP ホワイトリスト。半角 , で区切る
DW_TRUSTED_PROXIES
type: string
required: N
信頼済みプロキシの IP/CIDR。半角 , で区切る。信頼済みプロキシからのリクエストのみ、X-Forwarded-For または X-Real-IP を使用してホワイトリスト判定を行う
DW_HTTP_TIMEOUT
type: string
required: N
Dataway が Kodo または次の Dataway にリクエストする際のタイムアウト。デフォルトは 3s
DW_HTTP_MAX_IDLE_CONN_PERHOST
type: int
required: N
Dataway が Kodo にリクエストする際の最大アイドル接続数 Version-1.6.2
デフォルト値は 1000 Version-1.11.2
DW_HTTP_READ_TIMEOUT
type: string
required: N
受信リクエストの読み取り期限。http_read_timeout に対応し、デフォルトは 5m
DW_HTTP_WRITE_TIMEOUT
type: string
required: N
受信レスポンスの書き込み期限。アップロード時間と処理時間を含み、http_write_timeout に対応。デフォルトは 10m
DW_HTTP_IDLE_TIMEOUT
type: string
required: N
受信接続が次のリクエストを待つアイドル期限。http_idle_timeout に対応し、デフォルトは 2m
DW_HTTP_MAX_CONN_PERHOST
type: int
required: N
Dataway が Kodo にリクエストする際の最大接続数。デフォルトでは制限なし Version-1.6.2
DW_KODO_QUEUE_ENABLED
type: boolean
required: N
書き込み/アップロード/OTLP HTTP リクエストを Kodo または次の Dataway に送信する前の有界ディスパッチキューを有効化。デフォルトは true
DW_KODO_QUEUE_WORKERS
type: int
required: N
Kodo ディスパッチキューの worker 数。デフォルトは 256
DW_KODO_QUEUE_SIZE
type: int
required: N
Kodo ディスパッチキューで待機できる最大リクエスト数。デフォルトは 1024
DW_KODO_QUEUE_MAX_BYTES
type: int/string
required: N
Kodo キュー内で待機中、送信中、および入隊待ちのリクエスト body の合計バイト数上限。1073741824、1GB、1024MB などの形式をサポートし、デフォルトは 1GB
DW_KODO_QUEUE_ENQUEUE_TIMEOUT
type: string
required: N
リクエストが Kodo キューの空きを待つ最大時間。タイムアウト後、キャッシュ可能なリクエストは Dataway キャッシュに書き込まれ、キャッシュが利用できない場合は 503 を返します。デフォルトは 100ms
DW_TOKEN_NEGATIVE_CACHE_ENABLED
type: boolean
required: N
無効な token のネガティブキャッシュを有効にするかどうか。キャッシュは token、書き込み API パス、および main/headless モードごとに分離され、デフォルトは true
DW_TOKEN_NEGATIVE_CACHE_TTL
type: string
required: N
無効な token のネガティブキャッシュの有効期間。デフォルトは 5m
DW_TOKEN_NEGATIVE_CACHE_MAX_KEYS
type: int
required: N
無効な token のネガティブキャッシュで保存できる scope key の最大数。デフォルトは 1000
DW_BIND
type: string
required: N
Dataway HTTP API の IPv4 バインドアドレス。デフォルトは 0.0.0.0:9528
DW_BIND_IPV6
type: string
required: N
Dataway HTTP API の IPv6 バインドアドレス。デフォルトではリッスンしない。[::]:9528 を設定すると IPv6 リスンを明示的に有効化できる
DW_API_LIMIT
type: int
required: N
Dataway API のレート制限設定。たとえば 1000 に設定すると、各 API は 1 秒以内に 1000 回のみリクエストできます。デフォルトは 100K
DW_HEARTBEAT
type: string
required: N
Dataway とセンター間のハートビート間隔。デフォルトは 60s
DW_MAX_HTTP_BODY_BYTES
type: int
required: N
Dataway API が許可する最大 HTTP Body(単位はバイト)。デフォルトは 64MB
DW_TLS_INSECURE_SKIP_VERIFY
type: boolean
required: N
HTTPS/TLS 証明書エラーを無視
DW_HTTP_CLIENT_TRACE
type: boolean
required: N
Dataway 自身が HTTP クライアントとして動作する際に、関連するメトリクス収集を有効にできます。これらのメトリクスは最終的に Prometheus メトリクスとして出力されます
DW_ENABLE_TLS
type: boolean
required: N
HTTPS を有効化 Version-1.4.1
DW_TLS_CRT
type: file-path
required: N
HTTPS/TLS crt ファイルのディレクトリを指定 Version-1.4.0
DW_TLS_KEY
type: file-path
required: N
HTTPS/TLS key ファイルのディレクトリを指定 Version-1.4.0
DW_SNI
type: string
required: N
現在の Dataway の SNI 情報を指定 Version-1.6.0
DW_DISABLE_404PAGE
type: boolean
required: N
404 ページを無効化 Version-1.6.1
DW_HTTP_IP_BLACKLIST_TTL
type: string
required: N
IP ブラックリストの有効期間を設定。デフォルトは 1m Version-1.11.0
DW_HTTP_IP_BLACKLIST_CLEAN_INTERVAL
type: string
required: N
IP ブラックリストのクリーンアップ間隔を設定。デフォルトは 1h Version-1.11.0
HTTP TLS 設定

有効期間が 1 年の TLS 証明書を生成するには、以下の OpenSSL コマンドを使用できます:

# 有効期間 1 年の TLS 証明書を生成
$ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out tls.crt -keyout tls.key
...

このコマンドを実行すると、国、地域、都市、組織名、部門名、メールアドレスなどの必要な情報の入力が求められます。これらの情報は証明書に含まれます。

情報の入力が完了すると、tls.crt(証明書ファイル)と tls.key(秘密鍵ファイル)の 2 つのファイルが生成されます。秘密鍵ファイルは適切に保管し、安全性を確保してください。

アプリケーションでこれらの TLS 証明書を使用するには、2 つのファイルの絶対パスをアプリケーションの環境変数に設定する必要があります。環境変数の設定例を以下に示します:

先に DW_ENABLE_TLS を有効にする必要があります。そうすることで、残り 2 つの ENV(DW_TLS_CRT/DW_TLS_KEY)が有効になります。 Version-1.4.1

env:
- name: DW_ENABLE_TLS
  value: "true"
- name: DW_TLS_CRT
  value: "/path/to/your/tls.crt"
- name: DW_TLS_KEY
  value: "/path/to/your/tls.key"

/path/to/your/tls.crt と /path/to/your/tls.key は、実際に tls.crt と tls.key ファイルを配置したパスに置き換えてください。

設定後、以下のコマンドで TLS が有効かどうかをテストできます:

$ curl -k http://localhost:9528

成功した場合は、It's working! の ASCII Art 情報が表示されます。証明書が存在しない場合、Dataway のログに次のようなエラーが出力されます:

server listen(TLS) failed: open /path/to/your/tls.{crt,key}: no such file or directory

この場合、Dataway は起動できず、上記の curl コマンドもエラーになります:

$ curl -vvv -k http://localhost:9528
curl: (7) Failed to connect to localhost port 9528 after 6 ms: Couldn't connect to server

ログ設定

Env 説明
DW_LOG
type: string
required: N
ログパス。デフォルトは log。ログを標準出力に出力して収集しやすくする場合は、stdout を直接設定します
DW_LOG_LEVEL
type: string
required: N
デフォルトは info。debug を選択可能
DW_GIN_LOG
type: string
required: N
デフォルトは gin.log。ここでも stdout を設定して収集しやすくできます
DW_LOG_PKG_ID
type: bool
required: N
Version-1.12.0 ログにパッケージ ID を記録するかどうか。デフォルトは true

Token/UUID 設定

Env 説明
DW_UUID
type: string
required: Y
Dataway UUID。Dataway の作成時にシステムワークスペースで生成されます
DW_TOKEN
type: string
required: Y
通常はシステムワークスペースのデータアップロード Token
DW_SECRET_TOKEN
type: string
required: N
Sinker 機能を有効にする場合、この Token を設定できます
DW_ENABLE_INTERNAL_TOKEN
type: boolean
required: N
__internal__ をクライアント Token として許可します。この場合、デフォルトでシステムワークスペースの Token を使用します
DW_ENABLE_EMPTY_TOKEN
type: boolean
required: N
Token なしでデータをアップロードすることを許可します。この場合、デフォルトでシステムワークスペースの Token を使用します

Sinker 設定

Env 説明
DW_SECRET_TOKEN
type: string
required: N
Sinker 機能を有効にする場合、この Token を設定できます
DW_CASCADED
type: string
required: N
Dataway をカスケードするかどうか
DW_SINKER_ETCD_URLS
type: string
required: N
etcd アドレス一覧。, で区切る。例:http://1.2.3.4:2379,http://1.2.3.4:2380
DW_SINKER_ETCD_DIAL_TIMEOUT
type: string
required: N
etcd 接続タイムアウト。デフォルトは 30s
DW_SINKER_ETCD_KEY_SPACE
type: string
required: N
Sinker 設定が格納される etcd キー名(デフォルト /dw_sinker)
DW_SINKER_ETCD_USERNAME
type: string
required: N
etcd ユーザー名
DW_SINKER_ETCD_PASSWORD
type: string
required: N
etcd パスワード
DW_SINKER_FILE_PATH
type: file-path
required: N
ローカルファイルで sinker ルール設定を指定
DW_SINKER_CACHE_BUCKETS
type: int
required: N
Version-1.12.0 Sinker キャッシュのバケット数を指定。デフォルトは 64
DW_SINKER_CACHE_RESERVED_CAPACITY
type: int
required: N
Version-1.12.0 Sinker キャッシュの最大件数を指定。デフォルトは 100w(1<<20)
DW_SINKER_CACHE_TTL
type: int
required: N
Version-1.12.0 Sinker キャッシュ要素の有効期間を指定。デフォルトは 10m(10 分)
DW_SINKER_CACHE_PREALLOC
type: bool
required: N
Version-1.12.0 キャッシュメモリを事前割り当て。デフォルトは false
Warning

ローカルファイルと etcd の両方を指定した場合、ローカルファイルの Sinker ルールが優先されます。どちらも指定しない場合、sinker 機能は無効になります。

Prometheus メトリクス公開

Env 説明
DW_PROM_URL
type: string
required: N
Prometheus メトリクスの URL パス(デフォルト /metrics)
DW_PROM_LISTEN
type: string
required: N
Prometheus メトリクスの公開アドレス(デフォルト localhost:9090)
DW_PROM_DISABLED
type: boolean
required: N
Prometheus メトリクス公開を無効化
DW_PPROF_BIND
type: string
required: N
pprof リスンアドレス。デフォルトでは無効で、loopback アドレスのみ受け付けます。例:localhost:6060

ディスクキャッシュ設定

Env 説明
DW_DISKCACHE_DIR
type: file-path
required: N
キャッシュディレクトリを設定。このディレクトリは通常、外部ストレージです
DW_DISKCACHE_DISABLE
type: boolean
required: N
ディスクキャッシュを無効化。キャッシュを無効にしない場合は、この環境変数を削除する必要があります
DW_DISKCACHE_CLEAN_INTERVAL
type: string
required: N
キャッシュクリーンアップ間隔。デフォルトは 1s
DW_DISKCACHE_EXPIRE_DURATION
type: string
required: N
キャッシュの有効期限。デフォルトは 168h(7d)
DW_DISKCACHE_CAPACITY_MB
type: int
required: N
Version-1.6.0 利用可能なディスク容量を設定。単位は MB。デフォルトは 20GB
DW_DISKCACHE_BATCH_SIZE_MB
type: int
required: N
Version-1.6.0 単一のディスクキャッシュファイルの最大サイズを設定。単位は MB。デフォルトは 64MB
DW_DISKCACHE_MAX_DATA_SIZE_MB
type: int
required: N
Version-1.6.0 単一のキャッシュ内容(たとえば単一の HTTP body)の最大サイズを設定。単位は MB。デフォルトは 64MB。このサイズを超える単一データパケットは破棄されます
Tips

DW_DISKCACHE_DISABLE を設定するとディスクキャッシュを無効にできます。

パフォーマンス関連設定

Version-1.6.0

Env 説明
DW_COPY_BUFFER_DROP_SIZE
type: int
required: N
指定サイズ(単位はバイト)を超える単一の HTTP body バッファーは直ちにクリアされ、過剰なメモリ消費を防ぎます。デフォルト値は 256KB

Dataway API 一覧

診断およびローカル処理のインターフェースを除き、転送系インターフェースはそれぞれの token 検証ルールに従ってリクエストを Kodo または次の Dataway に転送します。Langfuse 互換インターフェースの認証動作については後述します。

GET /v1/ping

Version-1.11.0

  • API 説明:Dataway の現在のバージョン番号とリリース日を取得し、同時にクライアントリクエストの送信元 IP を返します。

DataWay で 404 ページが無効化されている場合(disable_404page)、このインターフェースはサービスを提供できません。

GET /v1/ntp

Version-1.6.0

  • API 説明:Dataway の現在の Unix タイムスタンプを取得(単位は秒)

POST /v1/write/:category

  • API 説明:Datakit がアップロードする各種収集データを受信
  • 下流 4xx:通常の書き込み、OpenLineage、OCSF 転送は共通のエラーハンドリングを使用し、HTTP ステータスコードを保持します。404 は {} を返します。その他の 4xx は、解析可能な JSON エラーボディから error_code を抽出し、その他のエラー詳細は転送しません。レスポンスボディが空、JSON でない、または error_code を解析できない場合は {} を返し、エラーボディの解析失敗によって 4xx を 500 に変更することはなくなりました。下流の 4xx はディスクキャッシュに入りません。

POST /v1/write/openlineage

  • API 説明:単一の OpenLineage RunEvent、JobEvent、または DatasetEvent JSON を受信し、リクエストをそのまま Kodo または次の Dataway に転送します。
  • リクエスト要件:
    • Content-Type は application/json である必要があり、media type パラメータ(例:application/json; charset=utf-8)を含めることができます
    • ワークスペース token は token query、X-Token header、または Authorization: Bearer <token> で渡すことができ、優先順位は token、X-Token、Bearer の順です
    • Bearer token は下流で使用される query token と X-Token に変換され、元の Authorization は透過されません
    • リクエストでは Content-Encoding: gzip を使用できます。Dataway は JSON を展開または解析せず、圧縮された body と関連ヘッダーはそのまま転送経路に入ります
    • gzip および非圧縮リクエスト以外の Content-Encoding は HTTP 415 を返します。空の body は HTTP 400 を返します
    • 下流失敗時は、他の /v1/write/* データとディスクキャッシュ、容量制限、FIFO 淘汰、およびリプレイポリシーを共有します。キャッシュは転送リクエストの元の値で URL、header、body を保存し、query token と X-Token は平文でディスクに書き込まれます。暗号化キーは不要です。今回の書き込みでキャッシュに成功した場合にのみ dataway.cached を返します。キャッシュが容量上限に達すると、古いレコードが淘汰される可能性があります。リプレイに失敗したレコードは通常のキャッシュポリシーに従って再度キューに入り、キャッシュの有効期限を超えると破棄されます
    • 下流接続に失敗し、かつキャッシュされていない場合は、ターゲット URL/token を含まない HTTP 503 を返し、Retry-After: 1 を付与します。下流 4xx は通常の書き込みおよび OCSF と共通のエラーハンドリングを使用し、Sinker がターゲットパスを書き換えてもこのルールは変わりません
  • DataKit の ddtrace コレクター経由で接続する場合、クライアントは POST /openlineage/api/v1/lineage を使用します。DataKit は設定済みの DataWay token を使用します。 上記の token 渡し方は、DataWay に直接接続する場合に適用されます。
  • HTTP 2xx は、DataWay がリクエストを受信またはキャッシュしたこと(200 レスポンスボディの error_code=dataway.cached)を示し、Kodo が非同期検証を完了したことや LN が保存されたことを示すものではありません。 OpenLineage の構造検証、展開後のリソース制限、workspace バインディング、およびイベントの冪等性は、下流の Lineage ingest が担当します。

POST /v1/ocsf_ingest

OCSF JSON を受信し、現在の Dataway でログ point に変換して、/v1/write/logging を介して固定の ocsf インデックスに書き込みます。集約やテールサンプリングを有効にする必要はありません。

  • リクエストは Content-Type: application/json を使用し、charset パラメータを許可します。非圧縮、Content-Encoding: identity、または gzip をサポートします。NDJSON やその他の圧縮エンコーディングはサポートしません。
  • 単一イベントオブジェクト、イベント配列、および {"events":[...]} のバッチラップをサポートします。トップレベルオブジェクトに class_uid が存在する場合は単一イベントとして処理し、それ以外は bundle として処理します。bundle の外側メタデータから point は生成されず、point 数は実際のイベント数に基づきます。
  • body を読み取る前に認証を実行します。token の抽出優先順位は query token、X-Token、X-Amz-Firehose-Access-Key の順です。空の token、内部 token、secret token は既存の設定および sink 互換ルールに従って処理されます。
  • 各イベントには、SemVer 1.x の metadata.version、非負整数の class_uid、および整数ミリ秒の time が必須です。time はナノ秒に変換した後、int64 の範囲内である必要があります。同じバッチ内で異なる 1.x バージョンやカテゴリを混在できます。完全な OCSF Schema 検証は行わず、外部 Schema サービスにもリクエストしません。
  • リクエストボディ、gzip 展開後の JSON、および変換後のバッチ全体の protobuf は、max_http_body_bytes(DW_MAX_HTTP_BODY_BYTES)の制限を受けます。デフォルトは 64 MiB です。制限を超えた場合はバッチ全体で 413 を返し、送信側でバッチを縮小します。Dataway は自動的に分割しません。

データポイントマッピングとフィールド制限

1 イベントにつき 1 つの point を生成し、measurement/source は ocsf に固定、時刻はイベントの time を使用し、ログの status は info に固定されます。OCSF の元の重大度およびイベント結果はログレベルを変更しません。

入力 出力
完全なイベント JSON 原文 message
トップレベルの message/status/source/date ocsf_message/ocsf_status/ocsf_source/ocsf_date
トップレベルの time point のナノ秒時間。元のミリ秒値は message 内に残る
その他の文字列、ブール値、数値 同名のフィールド。整数は int64 として保持し、非負の大きな整数には uint64 を使用でき、小数または指数形式には float64 を使用します。表現可能な範囲を超えた場合は 400 を返します
ネストされたオブジェクト ドット区切りパスのフィールド(例:src_endpoint.ip)。キー名内のドットは保持
配列 JSON 文字列のフィールド
null、空のオブジェクト 独立したフィールドを生成せず、原文内に保持

各 point のフィールド数は最大 1024 個で、生成される message と status を含みます。最終的なフィールド名は最大 256 バイト、単一の文字列値は最大 32 MiB で、message を含みます。制限を超えた場合はバッチ全体で 413 を返し、フィールドやフィールド値を自動的に切り詰めることはありません。

リクエストとレスポンス

OCSF 1.3.0 Authentication イベントの例:

curl -X POST 'https://dataway.example.com/v1/ocsf_ingest?token=<token>' \
  -H 'Content-Type: application/json' \
  --data-binary '{"metadata":{"version":"1.3.0","product":{"name":"example","vendor_name":"example"}},"class_uid":3002,"category_uid":3,"type_uid":300201,"activity_id":1,"severity_id":1,"time":1713632701123,"user":{"name":"alice"},"service":{"name":"ssh"}}'

このリクエストは、名前が ocsf、時刻が 1713632701123000000 の point を生成し、user.name=alice、service.name=ssh、および完全な message を含みます。呼び出し側が別の X-Storage-Index-Name を指定しても ocsf で上書きされ、キャッシュリプレイ時もこのインデックスが維持されます。

バッチ全体の変換検証に合格した後にのみ同期的に送信し、既存の Kodo 送信、sink、署名、キャッシュ、リプレイの経路を再利用します:

ステータスコード 意味
200 下流への送信成功。下流が空レスポンスの場合は body も空
200 + {"error_code":"dataway.cached"} キャッシュへの書き込みに成功し、後でリプレイされる。下流がすでに書き込んだことを示すものではない
400 空の body/バッチ、不正な JSON/イベント、数値の範囲外、またはフィールドマッピングの競合
413 リクエストボディ、protobuf、またはフィールド制限の超過
415 メディアタイプまたは圧縮エンコーディングが未対応
503 同時実行の受け入れ拒否、またはリクエストボディの読み取りタイムアウト

認証エラー、および送信失敗かつキャッシュできない場合のエラーは既存の経路に従います。このインターフェースは非同期受信キューを追加せず、重複排除や下流へのバッチ全体の書き込み原子性を保証しません。入口のステータスと所要時間は既存の HTTP メトリクスを使用し、送信とキャッシュのメトリクスは /v1/write/logging に基づいて集計されます。

JSON キーの重複とフィールド競合

同じ JSON オブジェクト内で重複キーが出現した場合、リクエスト原文の順序に従って最後に出現した値を保持し、重複キー自体を理由に 400 を返すことはありません。このルールは bundle の外側、イベントオブジェクト、ネストされたオブジェクト、および配列内のオブジェクトに適用されます。異なるオブジェクト間では互いに上書きしません。キー名は JSON エスケープを解除した文字列で比較し、たとえば class_uid と class\u005fuid は同名として扱います。重複キーの値がオブジェクトまたは配列の場合、後の値が前の値を全体として置き換え、マージは行いません。

フィールド検証と point マッピングは、最後に保持された値に基づきます。point の message は完全なイベント JSON 原文を保持し、重複キーとその元の値を含みます。重複排除後の JSON で原文を置き換えることはありません。最後に保持された値がフィールド要件を満たさない場合(たとえば class_uid が負数)、引き続き不正なイベントとしてバッチ全体で 400 を返します。

以下の単一イベントリクエストは変換検証に合格し、1 つの point を生成します。この point では class_uid=4001、user.name=bob となり、message には引き続き以下の完全な原文が保持されます:

{
  "metadata": {"version": "1.3.0"},
  "class_uid": 3002,
  "class_uid": 4001,
  "time": 1713632701123,
  "user": {"name": "alice", "name": "bob"}
}

名前変更またはドット区切りパス展開によって生じるフィールド競合は、引き続きバッチ全体で 400 を返し、point を 1 つも送信しません。たとえば {"a.b":1,"a":{"b":2}} では、2 つの異なるパスが展開後にどちらも a.b になるため、フィールドマッピングの競合に該当します。エラー説明には競合するフィールドパスと、1 から始まるイベント番号が含まれます。

POST /v1/aggregate

  • API 説明:メトリクス集約データを受信します。集約機能の初期化に成功した場合にのみ登録されます。
  • 詳細な動作モード、設定、およびリクエスト要件については、Dataway メトリクス集約を参照してください。

POST /v1/tail_sampling、POST /v1/tail_sampling_v2、POST /v2/tail_sampling および POST /v1/tail_sampling_config

  • API 説明:/v1/tail_sampling は raw テールサンプリングデータパケットを受信し、Datakit 2.10 が送信するネゴシエーションヘッダーなしの zstd データパケットと互換性があります。履歴パス /v1/tail_sampling_v2 は raw データパケットのみを受信します。/v2/tail_sampling は圧縮ネゴシエーションヘッダー付きの zstd データパケットを受信します。/v1/tail_sampling_config はテールサンプリング設定を受信します。テールサンプリング機能の初期化に成功した場合にのみ登録されます。
  • 詳細な動作モード、設定、およびリクエスト要件については、Dataway テールサンプリングを参照してください。

POST /otel/v1/{traces,metrics,logs}

Version-1.17.0

  • API 説明:OpenTelemetry OTLP HTTP/protobuf データを受信し、Kodo の対応するパスにそのまま転送します。
  • 対応パス:
    • POST /otel/v1/traces
    • POST /otel/v1/metrics
    • POST /otel/v1/logs
  • リクエスト要件:

    • Content-Type は application/x-protobuf である必要があり、media type パラメータ(例:application/x-protobuf; charset=utf-8)を含めることができます
    • ワークスペース token は token query、X-Token header、または Authorization: Bearer <token> で渡すことができます。Bearer token は転送前に X-Token に変換されます
    • OpenTelemetry SDK/Agent の環境変数を使用する場合、OTLP HTTP/protobuf を明示的に設定し、ベース endpoint を Dataway の /otel プレフィックスに設定することを推奨します。OpenTelemetry はシグナルに応じて /v1/traces、/v1/metrics、/v1/logs を自動的に追加します:
    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
    export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://dataway.example.com/otel/v1/logs
    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://dataway.example.com/otel/v1/traces
    export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://dataway.example.com/otel/v1/metrics
    export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20{token}"
    
    • 起動パラメータは環境変数と同じ意味です。Java Agent を例にすると、-Dotel.exporter.otlp.protocol=http/protobuf、-Dotel.exporter.otlp.endpoint=https://dataway.example.com/otel、-Dotel.exporter.otlp.headers=Authorization=Bearer%20{token} を設定できます。実装によって Authorization header 内のスペースエンコーディングの互換性が異なる場合は、OTEL_EXPORTER_OTLP_HEADERS="X-Token={token}" または対応する起動パラメータに変更することもできます。
    • Dataway は OTLP body を解析または書き換えません。/otel/v1/metrics は /v1/write/metric line protocol に変換されません。Kodo は DataKit のデフォルト OTLP metrics ルールに従って解析し、measurement は otel_service となり、メトリクスフィールド名は OTLP の元の metric name を保持します(たとえば runtime.jvm.memory は runtime_jvm_memory に書き換えられません)
    • Kodo が返す元の OTLP レスポンスステータス、レスポンス body、および必要なレスポンスヘッダーは透過されます。転送に失敗し、ディスクキャッシュポリシーを満たす場合、リクエストは Dataway のディスクキャッシュリプレイ経路に入ります

GET /v1/datakit/pull

  • API 説明:Datakit がセンター設定(ブラックリスト/Pipeline)を取得するリクエストを処理

POST /v1/datakit/usage_trace

  • API 説明:Datakit の使用状況追跡データを受信します。

POST /v1/write/rum/replay

  • API 説明:Datakit がアップロードする Session Replay データを受信

POST /v1/write/rum/replay_assets

  • API 説明:Session Replay に関連するリソースのアップロードリクエストを受信します。

POST /v1/check/rum/replay_assets

  • API 説明:Session Replay に関連するリソースが既に存在するかどうかを確認します。

POST /v1/upload/profiling

  • API 説明:Datakit がアップロードするプロファイリングデータを受信

POST /v1/input/firehose

  • API 説明:Firehose 入力データを受信します。

POST /v1/election

  • API 説明:Datakit の選出リクエストを処理

POST /v1/election/heartbeat

  • API 説明:Datakit の選出ハートビートリクエストを処理

POST /v1/query/raw

DQL クエリリクエストを処理します。簡単な例は次のとおりです:

POST /v1/query/raw?token=<workspace-token> HTTP/1.1
Content-Type: application/json

{
    "token": "workspace-token",
    "queries": [
        {
            "query": "M::cpu LIMIT 1"
        }
    ],
    "echo_explain": <true/false>
}

返却例:

{
  "content": [
    {
      "series": [
        {
          "name": "cpu",
          "columns": [
            "time",
            "usage_iowait",
            "usage_total",
            "usage_user",
            "usage_guest",
            "usage_system",
            "usage_steal",
            "usage_guest_nice",
            "usage_irq",
            "load5s",
            "usage_idle",
            "usage_nice",
            "usage_softirq",
            "global_tag1",
            "global_tag2",
            "host",
            "cpu"
          ],
          "values": [
            [
              1709782208662,
              0,
              7.421875,
              3.359375,
              0,
              4.0625,
              0,
              0,
              0,
              1,
              92.578125,
              0,
              0,
              null,
              null,
              "WIN-JCHUL92N9IP",
              "cpu-total"
            ]
          ]
        }
      ],
      "points": null,
      "cost": "24.558375ms",
      "is_running": false,
      "async_id": "",
      "query_parse": {
        "namespace": "metric",
        "sources": {
          "cpu": "exact"
        },
        "fields": {},
        "funcs": {}
      },
      "index_name": "",
      "index_store_type": "",
      "query_type": "guancedb",
      "complete": false,
      "index_names": "",
      "scan_completed": false,
      "scan_index": "",
      "next_cursor_time": -1,
      "sample": 1,
      "interval": 0,
      "window": 0
    }
  ]
}

返却結果の説明:

  • 実際のデータは内側の series フィールドにあります
  • name はメジャーメント名を表します(ここでは CPU メトリクスをクエリしています。ログ系データの場合はこのフィールドはありません)
  • columns は返却される結果列の名前を表します
  • values には columns に対応する列の結果が格納されます

Info
  • URL リクエストパラメータの token は、JSON body の token と異なっていてもかまいません。前者はクエリリクエストが正当かどうかを検証するために使用され、後者は対象データが存在するワークスペースを特定するために使用されます。
  • queries フィールドには複数のクエリを含めることができ、各クエリは追加フィールドを持てます。具体的なフィールド一覧については、こちらを参照してください。

POST /v1/workspace

  • API 説明:Datakit 側から発行されるワークスペースクエリリクエストを処理

GET /v1/env_variable

  • API 説明:ワークスペースの環境変数を取得します。

POST /v1/dataway/heartbeat

  • API 説明:Dataway のハートビート送信リクエストを受信します。

POST /v1/object/labels

  • API 説明:オブジェクトの Label 変更リクエストを処理

DELETE /v1/object/labels

  • API 説明:オブジェクトの Label 削除リクエストを処理

GET /v1/check/token/:token

  • API 説明:token が正当かどうかを検出します。

Langfuse 互換インターフェース

以下のインターフェースは Langfuse クライアントとの互換性のために提供され、リクエストは上流に直接転送されます。Dataway は token 検証を行いません:

  • POST /api/public/otel/v1/traces:Langfuse OTLP Trace データを受信します。
  • GET /api/public/projects:Langfuse プロジェクト情報を取得します。
  • POST /api/public/ingestion:Langfuse ingestion データを受信します。上流が成功したがレスポンスボディを返さない場合、 Dataway はリクエストバッチ内のイベント ID に基づいて、Langfuse SDK 4.x 互換の successes/errors JSON レスポンスを返します。

Dataway メトリクス収集

HTTP client メトリクス収集

Dataway が Kodo(または次の Dataway)に送信する HTTP リクエストのメトリクスを収集する場合は、http_client_trace 設定を手動で有効にする必要があります。または、環境変数 DW_HTTP_CLIENT_TRACE=true を指定します。

Dataway は自身で Prometheus メトリクスを公開しており、Datakit に付属する prom コレクターでそのメトリクスを収集できます。コレクターの設定例は次のとおりです:

[[inputs.prom]]
  ## Exporter URLs.
  urls = [ "http://localhost:9090/metrics", ]
  source = "dataway"
  election = true
  measurement_name = "dw" # dataway のメジャーメントは dw に固定。変更しないでください
[inputs.prom.tags]
  service = "dataway"

クラスタに Datakit(Datakit 1.14.2 以降が必要)がデプロイされている場合、Dataway で Prometheus メトリクス公開を有効にできます(Dataway のデフォルト Pod YAML には既に含まれています):

annotations: # 以下の annotation はデフォルトで追加済み
   datakit/prom.instances: |
     [[inputs.prom]]
       url = "http://$IP:9090/metrics" # ここのポート(デフォルト 9090)は状況に応じて設定
       source = "dataway"
       measurement_name = "dw" # このメジャーメントに固定
       interval = "10s"
       disable_instance_tag = true

     [inputs.prom.tags]
       service = "dataway"
       instance = "$PODNAME"

...
env:
- name: DW_PROM_LISTEN
  value: "0.0.0.0:9090" # ここのポートは上記 url のポートと一致させる

収集に成功すると、Guanceの「シーン」/「組み込みビュー」で dataway を検索すると、対応する監視ビューが表示されます。

キャッシュと Kodo キューのトラブルシューティング

tail_sampling_spill を有効にすると、その送信失敗は自身でリトライされ、HTTP 失敗キャッシュには入りません。容量とリトライのメトリクスについては、spill のトラブルシューティングを参照してください。

Kodo が 5xx を返した場合、Dataway から Kodo へのリクエストが失敗した場合、または Kodo ディスパッチキューが満杯の場合、Dataway はキャッシュ可能なリクエストをディスクキャッシュに書き込もうとします。Kodo の 4xx はキャッシュに入りません。

トラブルシューティングでは、以下のメトリクスを優先的に確認してください:

  • dataway_http_api_cached_bytes{reason=...}:リクエストがキャッシュに書き込まれました。一般的な reason には Kodo 5xx のステータステキスト、httpCliDoFailed、kodoQueueFull が含まれます。
  • dataway_http_api_dropped_cache{reason=...}:リクエストはキャッシュを試みましたが書き込まれませんでした。一般的な reason には feat-disabled、expected-api-drop、body-md5-not-matched、body-length-not-matched、expired、put-failed、sendopt-nil が含まれます。
  • dataway_kodo_queue_full_total{action=...}:Kodo キューが満杯になった後の処理結果。action="cache" はキャッシュに移行済み、action="reject" はキャッシュが利用できないか書き込みに失敗した後に 503 を返したことを示します。
  • dataway_http_concurrency_in_flight / dataway_http_concurrency_waiting:現在処理が許可されているリクエスト数と、まだ Body を読み取る前に待機しているリクエスト数。
  • dataway_http_concurrency_requests_total{result=...}:HTTP 同時実行制限の処理結果。admitted、waiting_full、wait_timeout、canceled を含みます。

Dataway メトリクス一覧

以下は Dataway が公開するメトリクスです。http://localhost:9090/metrics にリクエストすることで取得でき、以下のコマンドで特定のメトリクスをリアルタイム(3s)に確認できます:

一部のメトリクスがクエリできない場合、関連する業務モジュールがまだ実行されていない可能性があります。一部の新しいメトリクスは最新バージョンにのみ存在します。ここでは各メトリクスのバージョン情報を個別に記載しません。/metrics インターフェースが返すメトリクス一覧を基準にしてください。

watch -n 3 'curl -s http://localhost:9090/metrics | grep -a <METRIC-NAME>'
TYPE NAME LABELS HELP
SUMMARY dataway_kodo_queue_wait_seconds api,method Kodo queue wait duration before worker dispatch
SUMMARY dataway_http_concurrency_wait_seconds api,method,result HTTP concurrency wait duration
GAUGE dataway_http_concurrency_in_flight N/A Current HTTP requests being processed
GAUGE dataway_http_concurrency_waiting N/A Current HTTP requests waiting before their request bodies are read
COUNTER dataway_http_concurrency_requests_total api,method,result HTTP concurrency results
SUMMARY dataway_http_api_elapsed_seconds api,method,sinked,status API request latency
SUMMARY dataway_http_api_body_buffer_utilization api API body buffer utillization(Len/Cap)
SUMMARY dataway_http_api_body_copy api API body copy
SUMMARY dataway_http_api_body_copy_seconds api API body copy latency
SUMMARY dataway_http_api_body_copy_enlarge api API body copy enlarged pooled buffer
SUMMARY dataway_http_api_resp_size_bytes api,method,status API response size
SUMMARY dataway_http_api_req_size_bytes api,method,status API request size
COUNTER dataway_http_api_body_too_large_dropped_total api,method API request too large dropped
COUNTER dataway_http_api_with_inner_token api,method API request with inner token
COUNTER dataway_http_api_dropped_total api,method API request dropped when sinker rule match failed
COUNTER dataway_ip_blacklist_blocked_total api,method IP blacklist blocked requests total
COUNTER dataway_ip_blacklist_missed_total api,method IP blacklist missed total
COUNTER dataway_ip_blacklist_added_total api,method,reason IP blacklist added total
COUNTER dataway_syncpool_stats name,type sync.Pool usage stats
COUNTER dataway_http_api_copy_body_failed_total api API copy body failed count
COUNTER dataway_http_api_signed_total api,method API signature count
SUMMARY dataway_http_api_cached_bytes api,cache_type,method,reason API cached body bytes
SUMMARY dataway_http_api_reusable_body_read_bytes api,method API re-read body on forking request
SUMMARY dataway_http_api_recv_points api API /v1/write/:category recevied points
SUMMARY dataway_http_api_send_points api API /v1/write/:category send points
SUMMARY dataway_http_api_cache_points api,cache_type Disk cached /v1/write/:category points
SUMMARY dataway_http_api_cache_cleaned_points api,cache_type,status Disk cache cleaned /v1/write/:category points
COUNTER dataway_http_api_forked_total api,method,token API request forked total
GAUGE dataway_http_cli_info max_conn_per_host,max_idle_conn,max_idle_conn_per_host,timeout Dataway as client settings
GAUGE dataway_http_info cascaded,docker,http_client_trace,listen,max_body,release_date,remote,version Dataway API basic info
GAUGE dataway_kodo_queue_depth N/A Current Kodo dispatch queue depth including in-flight tasks
GAUGE dataway_kodo_queue_bytes N/A Current Kodo dispatch queue body bytes including in-flight tasks
COUNTER dataway_kodo_queue_enqueued_total api,method Kodo queue enqueued tasks
COUNTER dataway_kodo_queue_full_total api,method,action Kodo queue full events
COUNTER dataway_kodo_queue_dispatch_total api,method,status Kodo queue dispatch results
COUNTER dataway_token_negative_cache_added_total api,method,error_code Token negative cache added total
COUNTER dataway_token_negative_cache_blocked_total api,method,error_code Token negative cache blocked requests total
GAUGE dataway_last_heartbeat_time N/A Dataway last heartbeat with Kodo timestamp
SUMMARY dataway_http_api_copy_buffer_drop_total max API copy buffer dropped(too large cached buffer) count
GAUGE dataway_cpu_usage N/A Dataway CPU usage(%)
GAUGE dataway_mem_stat type Dataway memory usage stats
GAUGE dataway_open_files N/A Dataway open files
GAUGE dataway_open_files_by_type type Dataway open files grouped by fd type
GAUGE dataway_tcp_connections direction,port,state Dataway TCP connections grouped by direction, port and state(Linux only)
GAUGE dataway_cpu_cores N/A Dataway CPU cores
GAUGE dataway_uptime N/A Dataway uptime
COUNTER dataway_process_ctx_switch_total type Dataway process context switch count(Linux only)
COUNTER dataway_process_io_count_total type Dataway process IO count
COUNTER dataway_process_io_bytes_total type Dataway process IO bytes count
SUMMARY dataway_http_api_dropped_cache api,method,reason Dropped cache data dur to various reasons
COUNTER dataway_http_api_body_size_bytes_total api,token Accumulated API body bytes for aggregate or tailSampling
COUNTER dataway_http_aggr_point_total api,token point count of aggregate or tailSampling
COUNTER dataway_http_tail_sampling_trace_total token tailSampling trace count
COUNTER dataway_http_tail_sampling_span_total token tailSampling span count
COUNTER dataway_http_tail_sampling_packet_send_total token,data_type,result tailSampling packet send result count
GAUGE dataway_httpcli_dns_resolved_address api,coalesced,host,server HTTP DNS resolved address
SUMMARY dataway_httpcli_dns_cost_seconds api,coalesced,host,server HTTP DNS cost
SUMMARY dataway_httpcli_tls_handshake_seconds api,server HTTP TLS handshake cost
SUMMARY dataway_httpcli_http_connect_cost_seconds api,server HTTP connect cost
SUMMARY dataway_httpcli_got_first_resp_byte_cost_seconds api,server Got first response byte cost
SUMMARY http_latency api,server HTTP latency
COUNTER dataway_httpcli_tcp_conn_total api,server,remote,type HTTP TCP connection count
COUNTER dataway_httpcli_conn_reused_from_idle_total api,server HTTP connection reused from idle count
SUMMARY dataway_httpcli_conn_idle_time_seconds api,server HTTP connection idle time
GAUGE dataway_sinker_rule_cache_size name Sinker rule cache size
GAUGE dataway_sinker_rule_error error Rule errors
GAUGE dataway_sinker_default_rule_hit info Default sinker rule hit count
GAUGE dataway_sinker_rule_last_applied_time source,version Rule last applied time(Unix timestamp)
SUMMARY dataway_sinker_rule_cost_seconds type Rule cost time seconds
SUMMARY dataway_sinker_lru_cache_cleaned name Sinker LRU cache cleanup removed entries
COUNTER dataway_sinker_lru_cache_dropped_total bucket,name,reason Sinker LRU キャッシュから削除されたエントリの総数
HISTOGRAM dataway_sinker_lru_cache_expired_delay_seconds bucket,name Sinker LRU キャッシュの期限切れエントリのクリーンアップ遅延
HISTOGRAM dataway_sinker_lru_cache_evicted_remaining_ttl_seconds bucket,name Sinker LRU キャッシュの容量超過により削除されたエントリの残り TTL
COUNTER dataway_sinker_pull_total event,source Sinker pulled or pushed total
GAUGE dataway_sinker_rule_count type,with_default Sinker rule count
GAUGE dataway_sinker_rule_cache_get_total name,type Sinker rule cache get hit/miss count
COUNTER diskcache_rotate_total path Cache rotate count, mean file rotate from data to data.0000xxx
COUNTER diskcache_remove_total path Removed file count, if some file read EOF, remove it from un-read list
COUNTER diskcache_wakeup_total path Wakeup count on sleeping write file
COUNTER diskcache_pos_updated_total op,path .pos file updated count
COUNTER diskcache_seek_back_total path Seek back when Get() got any error
GAUGE diskcache_capacity path Current capacity(in bytes)
GAUGE diskcache_max_data path Max data to Put(in bytes), default 0
GAUGE diskcache_batch_size path Data file size(in bytes)
GAUGE diskcache_size path Current cache size that waiting to be consumed(get). The size include header bytes
GAUGE diskcache_open_time no_fallback_on_error,no_lock,no_pos,no_sync,path Current cache Open time in unix timestamp(second)
GAUGE diskcache_last_close_time path Current cache last Close time in unix timestamp(second)
GAUGE diskcache_datafiles path Current un-read data files
HISTOGRAM diskcache_lock_wait_seconds lock_type,path Time spent waiting for locks by lock type
COUNTER diskcache_lock_contention_total lock_type,path Number of lock contention events
SUMMARY diskcache_get_latency path Get() cost seconds
SUMMARY diskcache_put_latency path Put() cost seconds
SUMMARY diskcache_put_bytes path Cache Put() bytes
SUMMARY diskcache_get_bytes path Cache Get() bytes
SUMMARY diskcache_dropped_data path,reason Dropped data during Put() when capacity reached.

Docker モードでのメトリクス収集

ホストインストールには 2 つのモードがあり、1 つはホストマシンへのインストール、もう 1 つは Docker 経由のインストールです。ここでは Docker 経由でインストールした場合のメトリクス収集の違いについて個別に説明します。

Docker 経由でインストールする場合、メトリクス公開用 HTTP ポートは(デフォルトで)ホストマシンの 19090 ポートにマッピングされます。この場合、メトリクス収集アドレスは http://localhost:19090/metrics です。

異なるポートを個別に指定した場合、Docker インストールではそのポートに 10000 を加算します。そのため、ここで指定するポートは 45535 を超えないようにしてください。

pprof はデフォルトで無効で、Docker インストールでもホストマシンに profile ポートを公開しません。一時的なトラブルシューティング時には、pprof_bind または DW_PPROF_BIND を明示的に localhost:6060 に設定し、docker exec、kubectl exec、または制御されたポートフォワーディング経由で収集できます。loopback 以外のアドレスを設定した場合は拒否されます。

Dataway 自体のログ収集と処理

Dataway 自体のログは 2 種類に分かれ、1 つは gin ログ、もう 1 つは自身のプログラムログです。以下の Pipeline でこれらを分離できます:

# Pipeline for dataway logging

# Testing sample loggin
'''
2023-12-14T11:27:06.744+0800    DEBUG   apis    apis/api_upload_profile.go:272  save profile file to disk [ok] /v1/upload/profiling?token=****************a4e3db8481c345a94fe5a
[GIN] 2021/10/25 - 06:48:07 | 200 |   30.890624ms |  114.215.200.73 | POST     "/v1/write/logging?token=tkn_5c862a11111111111111111111111111"
'''

add_pattern("TOKEN", "tkn_\\w+")
add_pattern("GINTIME", "%{YEAR}/%{MONTHNUM}/%{MONTHDAY}%{SPACE}-%{SPACE}%{HOUR}:%{MINUTE}:%{SECOND}")
grok(_,"\\[GIN\\]%{SPACE}%{GINTIME:timestamp}%{SPACE}\\|%{SPACE}%{NUMBER:dataway_code}%{SPACE}\\|%{SPACE}%{NOTSPACE:cost_time}%{SPACE}\\|%{SPACE}%{NOTSPACE:client_ip}%{SPACE}\\|%{SPACE}%{NOTSPACE:method}%{SPACE}%{GREEDYDATA:http_url}")

# gin logging
if cost_time != nil {
  if http_url != nil  {
    grok(http_url, "%{TOKEN:token}")
    cover(token, [5, 15])
    replace(message, "tkn_\\w{0,5}\\w{6}", "****************$4")
    replace(http_url, "tkn_\\w{0,5}\\w{6}", "****************$4")
  }

  group_between(dataway_code, [200,299], "info", status)
  group_between(dataway_code, [300,399], "notice", status)
  group_between(dataway_code, [400,499], "warning", status)
  group_between(dataway_code, [500,599], "error", status)

  if sample(0.1) { # drop 90% debug log
    drop()
    exit()
  } else {
    set_tag(sample_rate, "0.1")
  }

  parse_duration(cost_time)
  duration_precision(cost_time, "ns", "ms")

  set_measurement('gin', true)
  set_tag(service,"dataway")
  exit()
}

# app logging
if cost_time == nil {
  grok(_,"%{TIMESTAMP_ISO8601:timestamp}%{SPACE}%{NOTSPACE:status}%{SPACE}%{NOTSPACE:module}%{SPACE}%{NOTSPACE:code}%{SPACE}%{GREEDYDATA:msg}")
  if level == nil {
    grok(message,"Error%{SPACE}%{DATA:errormsg}")
    if errormsg != nil {
      add_key(status,"error")
      drop_key(errormsg)
    }
  }
  lowercase(level)

  # if debug level enabled, drop most of them
  if status == 'debug' {
    if sample(0.1) { # drop 90% debug log
      drop()
      exit()
    } else {
      set_tag(sample_rate, "0.1")
    }
  }

  group_in(status, ["error", "panic", "dpanic", "fatal","err","fat"], "error", status) # mark them as 'error'

  if msg != nil {
    grok(msg, "%{TOKEN:token}")
    cover(token, [5, 15])
    replace(message, "tkn_\\w{0,5}\\w{6}", "****************$4")
    replace(msg, "tkn_\\w{0,5}\\w{6}", "****************$4")
  }

  set_measurement("dataway-log", true)
  set_tag(service,"dataway")
}

Dataway バグレポート

Dataway はメトリクスを公開し、必要に応じてプロファイリング収集エンドポイントを一時的に有効化して問題調査を行えます。pprof はデフォルトで無効です。収集前に pprof_bind を明示的に loopback アドレスに設定し、収集完了後に再度無効化する必要があります。

以下の情報収集は、実際に設定されたポートとアドレスに基づきます。

dw-bug-report.sh
br_dir="dw-br-$(date +%s)"
mkdir -p $br_dir

echo "save bug report to ${br_dir}"

# 実際の状況に応じてここの設定を変更
dw_ip="localhost" # dataway のメトリクス/profile 公開 IP アドレス
metric_port=9090  # メトリクス公開ポート
profile_port=6060 # 事前に localhost:6060 の pprof リスンを明示的に有効化する必要がある
dw_yaml_conf="/usr/local/cloudcare/dataflux/dataway/dataway.yaml"
dw_dot_yaml_conf="/usr/local/cloudcare/dataflux/dataway/.dataway.yaml" # コンテナインストール時にこのファイルが存在する

# ランタイムメトリクスを収集
curl -v "http://${dw_ip}:${metric_port}/metrics" -o $br_dir/metrics

# プロファイリング情報を収集
curl -v "http://${dw_ip}:${profile_port}/debug/pprof/allocs" -o $br_dir/allocs
curl -v "http://${dw_ip}:${profile_port}/debug/pprof/heap" -o $br_dir/heap
curl -v "http://${dw_ip}:${profile_port}/debug/pprof/profile" -o $br_dir/profile # このコマンドは 30 秒ほど実行される

cp $dw_yaml_conf $br_dir/dataway.yaml.copy
cp $dw_dot_yaml_conf $br_dir/.dataway.yaml.copy

tar czvf ${br_dir}.tar.gz ${br_dir}
rm -rf ${br_dir}

スクリプトを実行:

$ sh dw-bug-report.sh
...

実行後、dw-br-1721188604.tar.gz のようなファイルが生成されます。このファイルを取り出してください。

FAQ

リクエストボディが大きすぎる問題

Version-1.3.7

Dataway にはリクエストボディサイズのデフォルト設定(デフォルト 64MB)がありますが、リクエストボディが大きすぎる場合、クライアントは HTTP 413 エラー(Request Entity Too Large)を受け取ります。リクエストボディが妥当な範囲内であれば、この値(単位はバイト)を適切に大きくできます:

  • 環境変数 DW_MAX_HTTP_BODY_BYTES を設定
  • dataway.yaml で max_http_body_bytes を設定

実行中に大きすぎるリクエストパケットが発生した場合、メトリクスとログの両方に現れます:

  • メトリクス dataway_http_too_large_dropped_total は、破棄された大きなリクエストの数を公開します
  • Dataway ログを cat log | grep 'drop too large request' で検索します。ログには HTTP リクエストの Header 詳細が出力され、クライアントの状況をさらに把握できます
Warning

ディスクキャッシュモジュールにも、書き込めるデータブロックの最大サイズ制限(デフォルト 64MB)があります。最大リクエストボディの設定を増やす場合は、この設定も併せて調整し(ENV_DISKCACHE_MAX_DATA_SIZE)、大きなリクエストが正しくディスクキャッシュに書き込まれるようにしてください。


  1. この制限は、Dataway コンテナ/Pod の実行時にシステム制限により約 20000 接続しか使用できないことを避けるためのものです。制限を追加すると、Dataway のデータアップロード効率に影響します。Dataway のトラフィックが多い場合は、単一 Dataway の CPU 数を増やすか、Dataway インスタンスを水平スケールすることを検討できます。 ↩

フィードバック

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