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 使用独立 listener，避免依赖操作系统的 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

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，取消下面两行的注释
            # - 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 (개인 키 파일) 두 개의 파일이 생성됩니다. 개인 키 파일은 안전하게 보관하세요.

애플리케이션에서 이러한 TLS 인증서를 사용하려면 두 파일의 절대 경로를 애플리케이션의 환경 변수에 설정해야 합니다. 환경 변수 설정 예시는 다음과 같습니다:

먼저 DW_ENABLE_TLS를 활성화해야 다른 두 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 목록¶

진단 및 로컬 처리 인터페이스를 제외하고, 전달 유형 인터페이스는 각각의 token 검증 규칙에 따라 요청을 Kodo 또는 다음 홉 Dataway로 전달합니다. Langfuse 호환 인터페이스의 인증 동작은 아래 설명을 참조하세요.

GET /v1/ping¶

Version-1.11.0

• API 설명: Dataway의 현재 버전 번호 및 릴리스 날짜를 가져오고, 클라이언트 요청의 출구 IP를 반환합니다.

DataWay에서 404 페이지를 비활성화한 경우 (disable_404page), 이 인터페이스는 서비스를 제공할 수 없습니다.

GET /v1/ntp¶

Version-1.6.0

• API 설명: Dataway의 현재 Unix 타임스탬프 (초 단위)를 가져옵니다.

POST /v1/write/:category¶

• API 설명: Datakit이 업로드하는 다양한 수집 데이터를 수신합니다.

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은 token query, X-Token header 또는 Authorization: Bearer <token>을 통해 전달할 수 있습니다. Bearer token은 전달 전에 X-Token으로 변환됩니다.
  • OpenTelemetry SDK/Agent 환경 변수를 사용하는 경우 OTLP HTTP/protobuf를 명시적으로 구성하고 기본 endpoint를 Dataway의 /otel 접두사로 설정하는 것이 좋습니다. OpenTelemetry는 신호에 따라 자동으로 /v1/traces, /v1/metrics 및 /v1/logs를 추가합니다:

  export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
  export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://dataway.example.com/otel/v1/logs
  export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://dataway.example.com/otel/v1/traces
  export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://dataway.example.com/otel/v1/metrics
  export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20{token}"
  

  • 시작 매개변수는 환경 변수와 의미가 동일합니다. Java Agent의 예를 들면, -Dotel.exporter.otlp.protocol=http/protobuf, -Dotel.exporter.otlp.endpoint=https://dataway.example.com/otel 및 -Dotel.exporter.otlp.headers=Authorization=Bearer%20{token}를 구성할 수 있습니다. Authorization header의 공백 인코딩 호환성 문제가 있는 경우 OTEL_EXPORTER_OTLP_HEADERS="X-Token={token}" 또는 해당 시작 매개변수를 사용할 수도 있습니다.
  • Dataway는 OTLP body를 구문 분석하거나 다시 작성하지 않습니다. /otel/v1/metrics는 /v1/write/metric line protocol로 변환되지 않습니다. Kodo는 DataKit 기본 OTLP 메트릭 규칙에 따라 구문 분석하며, measurement는 otel_service이고 메트릭 필드 이름은 OTLP 원본 메트릭 이름을 유지합니다 (예: runtime.jvm.memory는 runtime_jvm_memory로 변경되지 않음).
  • Kodo에서 반환된 원본 OTLP 응답 상태, 응답 body 및 필요한 응답 header는 투과적으로 전달됩니다. 전달이 실패하고 디스크 캐시 정책이 충족되면 요청은 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 설명: 객체 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 메트릭 수집¶

[[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를 통해 설치하는 방식 두 가지가 있습니다. 여기서는 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 로그와 자체 프로그램 로그의 두 가지 유형으로 나뉩니다. 다음 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를 루프백 주소로 명시적으로 설정하고 수집이 완료된 후 다시 비활성화해야 합니다.

다음 정보 수집은 실제 구성된 포트와 주소를 기준으로 합니다.

br_dir="dw-br-$(date +%s)"
mkdir -p $br_dir

echo "save bug report to ${br_dir}"

# 실제 상황에 따라 여기서 구성 수정
dw_ip="localhost" # dataway 메트릭/프로파일이 노출된 IP 주소
metric_port=9090  # 메트릭 노출 포트
profile_port=6060 # 먼저 localhost:6060 pprof 수신을 명시적으로 활성화해야 함
dw_yaml_conf="/usr/local/cloudcare/dataflux/dataway/dataway.yaml"
dw_dot_yaml_conf="/usr/local/cloudcare/dataflux/dataway/.dataway.yaml" # 컨테이너 설치 시 이 파일이 있음

# 런타임 메트릭 수집
curl -v "http://${dw_ip}:${metric_port}/metrics" -o $br_dir/metrics

# 프로파일링 정보 수집
curl -v "http://${dw_ip}:${profile_port}/debug/pprof/allocs" -o $br_dir/allocs
curl -v "http://${dw_ip}:${profile_port}/debug/pprof/heap" -o $br_dir/heap
curl -v "http://${dw_ip}:${profile_port}/debug/pprof/profile" -o $br_dir/profile # 이 명령은 약 30초 동안 실행됨

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

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

스크립트 실행:

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

실행이 완료되면 dw-br-1721188604.tar.gz와 같은 파일이 생성됩니다. 이 파일을 가져오면 됩니다.

FAQ¶

요청 본문 크기 문제¶

Version-1.3.7

Dataway는 요청 본문 크기에 대한 기본 설정이 있습니다 (기본값 64MB). 요청 본문이 너무 크면 클라이언트는 HTTP 413 오류 (Request Entity Too Large)를 수신합니다. 요청 본문이 합리적인 범위 내에 있다면 이 값을 적절히 늘릴 수 있습니다 (바이트 단위):

• 환경 변수 DW_MAX_HTTP_BODY_BYTES 설정
• dataway.yaml에서 max_http_body_bytes 설정

실행 중에 너무 큰 요청 패킷이 발생하면 메트릭과 로그 모두에 표시됩니다:

• 메트릭 dataway_http_too_large_dropped_total은 폐기된 큰 요청 수를 노출합니다.
• Dataway 로그 cat log | grep 'drop too large request'를 검색하면 로그에 HTTP 요청의 Header 세부 정보가 출력되어 클라이언트 상황을 더 잘 이해할 수 있습니다.