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 デュアルスタックをサポートしていることを確認したうえで、以下の設定を同時に変更してください:
- Dataway コンテナの環境変数で
DW_BIND_IPV6のコメントを解除し、[::]:9528に設定して、Dataway が IPv4 と IPv6 の両方をリッスンするようにします。 - 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 にマウントする必要があります:
コンテナインストールに必要な環境変数は 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 にアップグレード可能なバージョンがある場合、「バージョン情報」にアップグレードの通知が表示されます。
Dataway サービスの管理¶
ホストに Dataway をインストールした場合、以下のコマンドで 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 が有効かどうかをテストできます:
成功した場合は、It's working! の ASCII Art 情報が表示されます。証明書が存在しない場合、Dataway のログに次のようなエラーが出力されます:
この場合、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 を設定するとディスクキャッシュを無効にできます。
パフォーマンス関連設定¶
| Env | 説明 |
|---|---|
| DW_COPY_BUFFER_DROP_SIZE type: int required: N |
指定サイズ(単位はバイト)を超える単一の HTTP body バッファーは直ちにクリアされ、過剰なメモリ消費を防ぎます。デフォルト値は 256KB |
Dataway API 一覧¶
診断およびローカル処理のインターフェースを除き、転送系インターフェースはそれぞれの token 検証ルールに従ってリクエストを Kodo または次の Dataway に転送します。Langfuse 互換インターフェースの認証動作については後述します。
GET /v1/ping¶
- API 説明:Dataway の現在のバージョン番号とリリース日を取得し、同時にクライアントリクエストの送信元 IP を返します。
DataWay で 404 ページが無効化されている場合(
disable_404page)、このインターフェースはサービスを提供できません。
GET /v1/ntp¶
- 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、またはDatasetEventJSON を受信し、リクエストをそのまま Kodo または次の Dataway に転送します。 - リクエスト要件:
Content-Typeはapplication/jsonである必要があり、media type パラメータ(例:application/json; charset=utf-8)を含めることができます- ワークスペース token は
tokenquery、X-Tokenheader、または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 を保存し、querytokenと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}¶
- API 説明:OpenTelemetry OTLP HTTP/protobuf データを受信し、Kodo の対応するパスにそのまま転送します。
- 対応パス:
POST /otel/v1/tracesPOST /otel/v1/metricsPOST /otel/v1/logs
-
リクエスト要件:
Content-Typeはapplication/x-protobufである必要があり、media type パラメータ(例:application/x-protobuf; charset=utf-8)を含めることができます- ワークスペース token は
tokenquery、X-Tokenheader、または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}を設定できます。実装によってAuthorizationheader 内のスペースエンコーディングの互換性が異なる場合は、OTEL_EXPORTER_OTLP_HEADERS="X-Token={token}"または対応する起動パラメータに変更することもできます。 - Dataway は OTLP body を解析または書き換えません。
/otel/v1/metricsは/v1/write/metricline 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/errorsJSON レスポンスを返します。
Dataway メトリクス収集¶
HTTP client メトリクス収集
Dataway が Kodo(または次の Dataway)に送信する HTTP リクエストのメトリクスを収集する場合は、http_client_trace 設定を手動で有効にする必要があります。または、環境変数 DW_HTTP_CLIENT_TRACE=true を指定します。
Dataway は自身で Prometheus メトリクスを公開しており、Datakit に付属する prom コレクターでそのメトリクスを収集できます。コレクターの設定例は次のとおりです:
クラスタに 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インターフェースが返すメトリクス一覧を基準にしてください。
| 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 アドレスに設定し、収集完了後に再度無効化する必要があります。
以下の情報収集は、実際に設定されたポートとアドレスに基づきます。
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}
スクリプトを実行:
実行後、dw-br-1721188604.tar.gz のようなファイルが生成されます。このファイルを取り出してください。
FAQ¶
リクエストボディが大きすぎる問題¶
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)、大きなリクエストが正しくディスクキャッシュに書き込まれるようにしてください。
-
この制限は、Dataway コンテナ/Pod の実行時にシステム制限により約 20000 接続しか使用できないことを避けるためのものです。制限を追加すると、Dataway のデータアップロード効率に影響します。Dataway のトラフィックが多い場合は、単一 Dataway の CPU 数を増やすか、Dataway インスタンスを水平スケールすることを検討できます。 ↩