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.18.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.18.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.18.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 /v1/tail_sampling_config¶

• API 説明：それぞれテールサンプリングデータパケットとテールサンプリング設定を受信します。テールサンプリング機能の初期化が成功した場合にのみ登録されます。
• 詳細な動作モード、設定、リクエスト要件については、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 クエリパラメータ、X-Token ヘッダー、または Authorization: Bearer <token> で渡すことができます。Bearer トークンは転送前に 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 ヘッダー内のスペースのエンコード互換性に問題がある場合は、代わりに 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 の元のメトリクス名（例: 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 がアップロードする Profiling データを受信します。

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 インストールでも profile ポートはホストに公開されません。一時的なトラブルシューティングの場合は、pprof_bind または DW_PPROF_BIND を明示的に localhost:6060 に設定し、docker exec、kubectl exec、または制御されたポートフォワーディングを介して収集してください。ループバックアドレス以外の設定は拒否されます。

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

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

# Dataway ログ用パイプライン

# テスト用サンプルログ
'''
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 ログ
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()
}

# アプリケーションログ
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 を明示的にループバックアドレスに設定し、収集が完了したら再度無効にしてください。

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

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