Dataway¶

概要¶

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

Dataway のインストール¶

• Dataway の新規作成

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

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

• 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)"

# ============= 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_max_idle_conn_perhost: 0 # default to CPU cores
http_max_conn_perhost: 0      # default no limit
kodo_queue:
  enabled: true
  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 は独立したリスナーを使用し、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 はデフォルトで無効。ループバックアドレスのみ許可します
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

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

---

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.19.0
          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

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

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.19.0

• Dataway インストールの確認

インストールが完了したら、少し待って「データゲートウェイ」ページを更新します。追加したデータゲートウェイの「バージョン情報」列にバージョン番号が表示されれば、この Dataway は Guance センターに正常に接続されています。フロントエンドユーザーはこれを使用してデータを取り込むことができます。

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

DataWay の管理¶

DataWay の削除¶

Guance 管理バックエンドの「データゲートウェイ」ページで、削除する 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.19.0

Dataway サービスの管理¶

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

# 起動
$ systemctl start dataway

# 再起動
$ systemctl restart dataway

# 停止
$ systemctl stop dataway

Kubernetes の場合は、対応する Pod を再起動してください。

環境変数¶

イメージ環境変数¶

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

HTTP Server 設定¶

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

ログ設定¶

Token/UUID 設定¶

Sinker 設定¶

Prometheus メトリクス公開¶

ディスクキャッシュ設定¶

パフォーマンス関連設定¶

Version-1.6.0

Dataway API 一覧¶

診断およびローカル処理インターフェースを除き、転送クラスのインターフェースは各々のトークン検証ルールに従って 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 がアップロードする各種収集データを受信します

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 である必要があり、メディアタイプパラメータ（例：application/x-protobuf; charset=utf-8）の指定が許可されます
  • スペーストークンは token query、X-Token ヘッダー、または Authorization: Bearer <token> で渡せます。Bearer トークンは転送前に X-Token に変換されます
  • OpenTelemetry SDK/Agent の環境変数を使用する場合、OTLP HTTP/protobuf を明示的に設定し、ベースエンドポイントを 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 ヘッダー内のスペースのエンコード互換性に問題がある場合は、OTEL_EXPORTER_OTLP_HEADERS="X-Token={token}" または対応する起動パラメータを使用することもできます。
  • Dataway は OTLP body を解析も書き換えもしません。/otel/v1/metrics は /v1/write/metric line protocol に変換されません。Kodo は DataKit デフォルトの OTLP metrics ルールに従って解析し、メジャーメントは otel_service、メトリクスフィールド名は OTLP の元のメトリクス名（例：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 に対応する列の結果です

POST /v1/workspace¶

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

GET /v1/env_variable¶

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

POST /v1/dataway/heartbeat¶

• API 説明：Dataway ハートビート報告リクエストを受信します。

POST /v1/object/labels¶

• API 説明：オブジェクトラベルの変更リクエストを処理します

DELETE /v1/object/labels¶

• API 説明：オブジェクトラベルの削除リクエストを処理します

GET /v1/check/token/:token¶

• API 説明：トークンが有効かどうかを確認します。

Langfuse 互換インターフェース¶

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

• POST /api/public/otel/v1/traces：Langfuse OTLP Trace データを受信します。
• GET /api/public/projects：Langfuse プロジェクト情報を取得します。
• POST /api/public/ingestion：Langfuse ingestion データを受信します。

Dataway メトリクス収集¶

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

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 キューのトラブルシューティング¶

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 メトリクス一覧¶

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

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

watch -n 3 'curl -s http://localhost:9090/metrics | grep -a <METRIC-NAME>'

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

ホストインストールには、ホストマシンへの直接インストールと Docker を使用したインストールの 2 つのモードがあります。ここでは Docker を使用したインストール時のメトリクス収集の違いについて説明します。

Docker を使用してインストールする場合、メトリクス公開用の HTTP ポートはホストマシンの 19090 ポート（デフォルト）にマッピングされます。この場合、メトリクス収集アドレスは http://localhost:19090/metrics になります。

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

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

Dataway 自身のログ収集と処理¶

Dataway 自身のログは、gin ログと自身のプログラムログの 2 種類に分類されます。以下の 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 はメトリクスを公開し、必要に応じて profiling 収集エントリを一時的に有効にして問題を調査できます。pprof はデフォルトで無効です。収集前に pprof_bind を明示的にループバックアドレスに設定し、収集完了後は再度無効にしてください。

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

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

# profiling 情報を収集
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 リクエストのヘッダー詳細が出力され、クライアントの状況をさらに把握できます