콘텐츠로 이동

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는 독립 리스너를 사용하여 운영 체제의 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를 리슨하려면 아래 두 줄의 주석을 해제
            # - name: DW_BIND_IPV6
            #   value: "[::]:9528"
            - name: DW_UUID
              value: agnt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Dataway UUID
            - name: DW_TOKEN
              value: tkn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # Dataway token
            - name: DW_PROM_LISTEN
              value: 0.0.0.0:9090
            - name: DW_LOG
              value: stdout
            - name: DW_LOG_LEVEL
              value: info
            - name: DW_GIN_LOG
              value: stdout
            - name: DW_DISKCACHE_DIR
              value: cache
            - name: DW_HTTP_TIMEOUT
              value: '3s'
            - name: DW_ENABLE_INTERNAL_TOKEN
              value: 'false'
            - name: DW_MAX_HTTP_BODY_BYTES
              value: '67108864'
            - name: DW_HTTP_CLIENT_TRACE
              value: 'on'
            - name: DW_RESERVED_POOL_SIZE
              value: '0'
            - name: DW_COPY_BUFFER_DROP_SIZE
              value: '262144'
            - name: DW_DISKCACHE_CAPACITY_MB
              value: 102400
          image: pubrepo.guance.com/dataflux/dataway:1.22.2
          imagePullPolicy: IfNotPresent
          name: dataway
          ports:
            - containerPort: 9528
              name: 9528tcp01
              protocol: TCP
          resources:
            limits:
              cpu: '4'
              memory: 4Gi
            requests:
              cpu: 100m
              memory: 512Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
          volumeMounts:
            - mountPath: /usr/local/cloudcare/dataflux/dataway/cache
              name: dataway-cache
      dnsPolicy: ClusterFirst
      imagePullSecrets: []
      #nodeSelector:
      #  nodepool: dataway
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
      #tolerations:
      #  - effect: NoSchedule
      #    key: nodepool
      #    operator: Equal
      #    value: dataway
  updateStrategy:
    rollingUpdate:
      partition: 0
    type: RollingUpdate
  volumeClaimTemplates:
    - apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
        name: dataway-cache
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 100Gi
        storageClassName: xxxxxx  # High-Performance Storage StorageClass
        volumeMode: Filesystem
      status:
        phase: Pending

---

apiVersion: v1
kind: Service
metadata:
  name: dataway
  namespace: utils
spec:
  ipFamilyPolicy: SingleStack # 듀얼 스택 모드에서는 PreferDualStack으로 변경
  # ipFamilies:
  #   - IPv4
  #   - IPv6
  ports:
    - name: 9528tcp02
      nodePort: 30928
      port: 9528
      protocol: TCP
      targetPort: 9528
  selector:
    app: sts-utils-dataway
  type: NodePort

기본 예시는 IPv4 단일 스택을 사용합니다. 듀얼 스택을 활성화하려면 Kubernetes 클러스터 및 CNI가 IPv4/IPv6 듀얼 스택을 지원하는지 확인한 후 다음 구성을 동시에 수정하세요:

  1. Dataway 컨테이너 환경 변수에서 DW_BIND_IPV6의 주석을 해제하고 [::]:9528로 설정하여 Dataway가 IPv4와 IPv6를 동시에 리슨하도록 합니다.
  2. Service의 ipFamilyPolicy를 SingleStack에서 PreferDualStack으로 변경하고 ipFamilies 아래 IPv4, IPv6의 주석을 해제합니다.

두 항목은 반드시 동시에 활성화해야 합니다. Service만 수정하고 DW_BIND_IPV6를 설정하지 않으면 Dataway는 IPv6 요청을 수신하지 않습니다.

dataway-statefulset.yaml에서 환경 변수를 통해 Dataway 구성을 수정할 수 있습니다. 여기를 참고하세요.

ConfigMap으로 dataway.yaml을 외부에 둘 수도 있지만, 반드시 /usr/local/cloudcare/dataflux/dataway/dataway.yaml로 마운트해야 합니다:

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

컨테이너 설치에 필요한 환경 변수는 Kubernetes와 동일합니다. 다음 Docker 명령으로 DataWay 컨테이너를 시작할 수 있습니다:

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

주의 사항
  • Dataway는 Linux 시스템에서만 실행할 수 있습니다(현재 Linux arm64/amd64 바이너리만 배포됨)
  • 호스트 설치 시 Dataway 설치 경로는 /usr/local/cloudcare/dataflux/dataway입니다
  • Kubernetes에서는 기본적으로 4000m/4Gi 리소스 제한이 설정되어 있으며, 실제 상황에 따라 조정할 수 있습니다. 최소 요구 사항은 100m/512Mi입니다
  • Dataway 설치 확인

설치가 완료되면 잠시 기다린 후 「데이터 게이트웨이」 페이지를 새로 고침합니다. 방금 추가한 데이터 게이트웨이의 「버전 정보」 열에서 버전 번호가 보이면 해당 Dataway가 Guance 센터에 성공적으로 연결되었으며, 프런트엔드 사용자가 이를 통해 데이터를 연동할 수 있음을 의미합니다.

Dataway가 Guance 센터에 성공적으로 연결되면 Guance 콘솔에 로그인하여 「통합」/「DataKit」 페이지에서 모든 Dataway 주소를 확인할 수 있습니다. 필요한 Dataway 게이트웨이 주소를 선택하고 DataKit 설치 명령을 가져와 서버에서 실행하면 데이터 수집을 시작할 수 있습니다.

DataWay 관리

DataWay 삭제

Guance 관리 백엔드의 「데이터 게이트웨이」 페이지에서 삭제할 DataWay를 선택하고 「구성」을 클릭한 후, 팝업되는 DataWay 편집 대화 상자에서 왼쪽 아래의 「삭제」 버튼을 클릭하면 됩니다.

Warning

DataWay를 삭제한 후에도 DataWay 게이트웨이가 배포된 서버에 로그인하여 DataWay 실행을 중지하고 설치 디렉터리를 삭제해야 DataWay가 완전히 삭제됩니다.

DataWay 업그레이드

Guance 관리 백엔드의 「데이터 게이트웨이」 페이지에서 DataWay에 업그레이드 가능한 버전이 있으면 버전 정보에 업그레이드 안내가 표시됩니다.

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

이미지 버전만 교체하면 됩니다:

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

Dataway 서비스 관리

호스트에 Dataway를 설치한 경우 다음 명령으로 Dataway 서비스를 관리할 수 있습니다.

# 시작
$ systemctl start dataway

# 재시작
$ systemctl restart dataway

# 중지
$ systemctl stop dataway

Kubernetes에서는 해당 Pod를 재시작하면 됩니다.

환경 변수

이미지 환경 변수

Dataway가 Kubernetes 환경에서 실행될 때 다음 환경 변수를 지원합니다.

기존 dataway.yaml과의 호환성

일부 오래된 Dataway는 ConfigMap 방식으로 구성을 주입합니다(컨테이너에 마운트되는 파일명은 일반적으로 dataway.yaml). Dataway 이미지 시작 후 설치 디렉터리에 ConfigMap으로 마운트된 파일이 있으면 아래 DW_* 환경 변수는 적용되지 않습니다. 기존 ConfigMap 마운트를 제거한 후에야 이러한 환경 변수가 적용됩니다.

환경 변수가 적용되면 Dataway 설치 디렉터리에 숨겨진( ls -a로 확인) .dataway.yaml 파일이 생성되며, cat 으로 해당 파일을 확인하여 환경 변수 적용 상태를 확인할 수 있습니다.

HTTP Server 설정

HTTP 요청은 Body를 읽기 전에 동시성 제한을 수행하며, 상한은 kodo_queue.workers(환경 변수 DW_KODO_QUEUE_WORKERS)를 재사용하고 기본값은 256입니다. 설정하지 않았거나 양수가 아니면 기본값을 사용합니다. 상한에 도달하면 최대 128개의 요청을 추가로 대기시키며, 최대 1s 동안 기다립니다. 대기 중에는 Body를 읽지 않습니다. 요청 처리가 끝나면 동시성 슬롯을 해제합니다. 대기 공간이 가득 차거나 시간 초과 시 등록된 DK 호환 인터페이스는 503을, 나머지 인터페이스는 429를 반환합니다. 모두 Retry-After: 1을 포함하며, 이러한 요청은 디스크 캐시에 들어가지 않습니다. 이 상태 코드 구분은 HTTP 동시성 승인 거부에만 사용되며, 이후 포워딩 및 캐싱의 오류 응답을 변경하지 않습니다. Body가 있는 모든 요청은 동일한 동시성 제한을 공유하며, Body가 없는 요청은 포함되지 않습니다. HTTP 동시성 제한은 Kodo worker와 구성 값을 공유하지만 특정 worker에 바인딩되지 않으며, Kodo 디스패치 큐를 닫아도 HTTP 동시성 제한은 닫히지 않습니다. 이 제한은 Pod 전체 메모리를 보장하지 않습니다.

HTTP/1.x 요청이 동시성 제한으로 거부되면 Dataway는 나머지 Body 읽기를 종료하고 응답을 반환한 후 연결을 닫습니다. 클라이언트가 재시도할 때는 새 연결을 설정해야 합니다.

인바운드 HTTP 요청은 다음 기한을 사용하며, 모두 다운스트림의 http_timeout과 독립적입니다:

구성 항목 기본값 역할
http_read_timeout 5m 전체 Body 업로드 시간 제한, HTTP/1.x는 요청 헤더 읽기 시간도 포함하며 소량의 데이터를 계속 전송해도 기한이 연장되지 않음
http_write_timeout 10m 응답 쓰기 기한 제한, 업로드 및 요청 처리 시간 포함
http_idle_timeout 2m 장기 연결이 다음 요청을 기다리는 유휴 시간 제한

요청 Body 읽기 타임아웃은 재시도 가능한 503(dataway.httpBodyReadTimeout)을 반환하고 동시성 슬롯을 해제하며, 완전히 수신되지 않은 데이터는 캐시하지 않습니다. 스트리밍 포워딩의 다운스트림은 이미 일부 데이터를 수신했을 수 있으므로 클라이언트는 여전히 재시도해야 합니다.

요청 헤더 읽기 기한은 여전히 10s입니다. 쓰기 기한은 읽기 기한에 예상 처리 소요 시간을 더한 값보다 커야 합니다. 위 항목은 모두 네트워크 읽기/쓰기 기한이며 CPU 계산을 강제로 종료하지 않습니다.

RUM은 첫 바이트를 읽기 전에 로컬 token 검증을 수행합니다. 누락되었거나 로컬 구성에서 거부된 token은 즉시 해당 인증 오류를 반환합니다. HTTP/1.x는 나머지 Body 읽기를 종료하고 연결을 닫으며 업로드 타임아웃을 기다리지 않습니다. 빈 token, 내부 token 및 비 sink 요청의 secret token 허용 호환 규칙은 변경되지 않습니다. 집계 및 테일 샘플링의 proxy 모드는 백엔드 연결 실패 시 502(dataway.proxyFailed)를 반환하며, 백엔드가 이미 반환한 응답은 빈 응답을 포함해 해당 상태 코드를 유지합니다.

세 구성 모두 양수여야 합니다. 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에 요청할 때 최대 idle connection 설정 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는 1s 이내에 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(개인 키 파일). 개인 키 파일을 안전하게 보관하고 보안을 유지하세요.

애플리케이션이 이러한 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

로그 설정

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 key 이름(기본 /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 Path(기본 /metrics)
DW_PROM_LISTEN
type: string
required: N
Prometheus 메트릭 노출 주소(기본 localhost:9090)
DW_PROM_DISABLED
type: boolean
required: N
Prometheus 메트릭 노출 비활성화
DW_PPROF_BIND
type: string
required: N
pprof 리슨 주소, 기본적으로 비활성화되며 loopback 주소만 허용합니다. 예: localhost:6060

디스크 캐시 설정

Env 설명
DW_DISKCACHE_DIR
type: file-path
required: N
캐시 디렉터리 설정, 해당 디렉터리는 일반적으로 외부 스토리지
DW_DISKCACHE_DISABLE
type: boolean
required: N
디스크 캐시 비활성화, 캐시를 비활성화하지 않으려면 이 환경 변수를 삭제해야 합니다
DW_DISKCACHE_CLEAN_INTERVAL
type: string
required: N
캐시 정리 간격, 기본 1s
DW_DISKCACHE_EXPIRE_DURATION
type: string
required: N
캐시 만료 시간, 기본 168h(7d)
DW_DISKCACHE_CAPACITY_MB
type: int
required: N
Version-1.6.0 사용 가능한 디스크 공간 크기 설정, 단위 MB, 기본 20GB
DW_DISKCACHE_BATCH_SIZE_MB
type: int
required: N
Version-1.6.0 단일 디스크 캐시 파일 최대 크기 설정, 단위 MB, 기본 64MB
DW_DISKCACHE_MAX_DATA_SIZE_MB
type: int
required: N
Version-1.6.0 단일 캐시 콘텐츠(예: 단일 HTTP body) 최대 크기 설정, 단위 MB, 기본 64MB. 이 크기를 초과하는 단일 데이터 패킷은 삭제됩니다
Tips

DW_DISKCACHE_DISABLE을 설정하면 디스크 캐시를 비활성화할 수 있습니다.

성능 관련 설정

Version-1.6.0

Env 설명
DW_COPY_BUFFER_DROP_SIZE
type: int
required: N
지정 크기(단위 바이트)를 초과하는 단일 HTTP body buffer는 즉시 지워 메모리 소비를 줄입니다. 기본값 256KB

Dataway API 목록

진단 및 로컬 처리 인터페이스를 제외하고, 포워딩类 인터페이스는 각자의 token 검증 규칙에 따라 요청을 Kodo 또는 다음 홉 Dataway로 포워딩합니다. Langfuse 호환 인터페이스의 인증 동작은 후문을 참고하세요.

GET /v1/ping

Version-1.11.0

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

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

GET /v1/ntp

Version-1.6.0

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

POST /v1/write/:category

  • API 설명: Datakit이 업로드하는 다양한 수집 데이터를 수신합니다.
  • 다운스트림 4xx: 일반 쓰기, OpenLineage 및 OCSF 포워딩은 공통 오류 처리를 사용하며 HTTP 상태 코드를 유지합니다. 404는 {}를 반환하고, 기타 4xx는 파싱 가능한 JSON 오류 본문에서 error_code를 추출하며 다른 오류 상세 정보는 포워딩하지 않습니다. 응답 본문이 비어 있거나 JSON이 아니거나 error_code를 파싱할 수 없으면 {}를 반환하며, 오류 본문 파싱 실패로 인해 4xx를 500으로 변경하지 않습니다. 다운스트림 4xx는 디스크 캐시에 들어가지 않습니다.

POST /v1/write/openlineage

  • API 설명: 단일 OpenLineage RunEvent, JobEvent 또는 DatasetEvent JSON을 수신하고 요청을 그대로 Kodo 또는 다음 홉 Dataway로 포워딩합니다.
  • 요청 요구 사항:
    • Content-Type은 반드시 application/json이어야 하며, media type 파라미터(예: application/json; charset=utf-8)를 포함할 수 있습니다.
    • 워크스페이스 token은 token query, X-Token header 또는 Authorization: Bearer <token>으로 전달할 수 있으며, 우선순위는 token, X-Token, Bearer 순입니다.
    • Bearer token은 다운스트림에서 사용하는 query token 및 X-Token으로 변환되며, 원본 Authorization은 전달되지 않습니다.
    • 요청은 Content-Encoding: gzip을 사용할 수 있습니다. Dataway는 JSON을 압축 해제하거나 파싱하지 않으며, 압축된 body와 관련 header는 그대로 포워딩 체인으로 들어갑니다.
    • gzip 및 비압축 요청 외의 다른 Content-Encoding은 HTTP 415를 반환하며, 빈 body는 HTTP 400을 반환합니다.
    • 다운스트림 실패 시 다른 /v1/write/* 데이터와 디스크 캐시, 용량 제한, FIFO 제거 및 재생 정책을 공유합니다. 캐시는 포워딩 요청 원본 값대로 URL, header 및 body를 저장하며, query token과 X-Token은 평문으로 디스크에 기록됩니다. 암호화 키는 필요하지 않습니다. 이번 쓰기가 캐시에 성공한 경우에만 dataway.cached를 반환합니다. 캐시가 용량 상한에 도달하면 이전 레코드가 제거될 수 있으며, 재생 실패 레코드는 일반 캐시 정책에 따라 다시 대기열에 들어가고 캐시 만료 시간을 초과하면 삭제됩니다.
    • 다운스트림 연결 실패 및 미캐시 시 대상 URL/token을 포함하지 않는 HTTP 503을 반환하며 Retry-After: 1을 함께 제공합니다. 다운스트림 4xx는 일반 쓰기 및 OCSF와 공통 오류 처리를 사용하며, Sinker가 대상 경로를 재작성해도 이 규칙은 변경되지 않습니다.
  • DataKit의 ddtrace 수집기를 통해 연동할 때 클라이언트는 POST /openlineage/api/v1/lineage를 사용합니다. DataKit은 이미 구성된 DataWay token을 사용하며, 위 token 전달 방식은 DataWay에 직접 연결할 때 적용됩니다.
  • HTTP 2xx는 DataWay가 요청을 수신했거나 캐시했음(200 응답 본문의 error_code=dataway.cached)을 의미하며, Kodo가 비동기 검증을 완료했거나 LN이 이미 저장되었음을 의미하지 않습니다. OpenLineage 구조 검증, 압축 해제 후 리소스 제한, workspace 바인딩 및 이벤트 멱등성은 다운스트림 Lineage ingest가 담당합니다.

POST /v1/ocsf_ingest

OCSF JSON을 수신하여 현재 Dataway에서 로그 point로 변환하고, /v1/write/logging을 통해 고정된 ocsf 인덱스에 기록합니다. 집계 또는 테일 샘플링을 활성화할 필요가 없습니다.

  • 요청은 Content-Type: application/json을 사용하며 charset 파라미터를 허용합니다. 비압축, Content-Encoding: identity 또는 gzip을 지원합니다. NDJSON 또는 기타 압축 인코딩은 지원하지 않습니다.
  • 단일 이벤트 객체, 이벤트 배열 및 {"events":[...]} 배치 래핑을 지원합니다. 최상위 객체에 class_uid가 있으면 단일 이벤트로 처리하고, 그렇지 않으면 bundle로 처리합니다. bundle 외부 메타데이터는 point를 생성하지 않으며, point 수는 실제 이벤트 수를 기준으로 합니다.
  • body를 읽기 전에 인증을 수행합니다. token 추출 우선순위는 query token, X-Token, X-Amz-Firehose-Access-Key입니다. 빈 token, 내부 token 및 secret token은 기존 구성 및 sink 호환 규칙에 따라 처리됩니다.
  • 각 이벤트에는 SemVer 1.x의 metadata.version, 음수가 아닌 정수 class_uid, 정수 밀리초 time이 포함되어야 합니다. time은 나노초로 변환된 후 int64 범위 내에 있어야 합니다. 동일 배치에서 서로 다른 1.x 버전과 카테고리를 혼합할 수 있으며, 전체 OCSF Schema 유효성 검사를 수행하지 않고 외부 Schema 서비스도 요청하지 않습니다.
  • 요청 body, gzip 압축 해제 후 JSON 및 변환된 전체 배치 protobuf는 모두 max_http_body_bytes(DW_MAX_HTTP_BODY_BYTES) 제한을 받으며 기본값은 64 MiB입니다. 초과 시 배치 전체에 413을 반환하며, 전송 측에서 배치 크기를 줄여야 하고 Dataway는 자동으로 분할하지 않습니다.

데이터 포인트 매핑 및 필드 제한

이벤트 하나당 하나의 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 요청 body, protobuf 또는 필드 제한 초과
415 미디어 유형 또는 압축 인코딩 미지원
503 동시성 승인 거부 또는 요청 body 읽기 타임아웃

인증 오류 및 전송 실패로 캐시할 수 없을 때의 오류는 기존 경로를 따릅니다. 인터페이스는 비동기 수신 큐를 새로 추가하지 않으며, 중복 제거 또는 다운스트림 전체 배치 쓰기의 원자성을 보장하지 않습니다. 진입 상태와 소요 시간은 기존 HTTP 메트릭을 사용하며, 전송 및 캐시 메트릭은 /v1/write/logging 기준으로 집계됩니다.

중복 JSON 키와 필드 충돌

동일한 JSON 객체 내에 중복 키가 있으면 요청 원문 순서에 따라 마지막으로 나타난 값을 유지하며, 중복 키 자체 때문에 400을 반환하지 않습니다. 이 규칙은 bundle 외부, 이벤트 객체, 중첩 객체 및 배열 내 객체에 적용되며, 서로 다른 객체 간에는 덮어쓰지 않습니다. 키 이름은 JSON 이스케이프를 디코딩한 문자열로 비교하며, 예를 들어 class_uid와 class\u005fuid는 같은 이름으로 간주합니다. 중복 키의 값이 객체 또는 배열이면 뒤의 값이 앞의 값을 전체 교체하며 병합하지 않습니다.

필드 유효성 검사와 point 매핑은 마지막으로 유지된 값을 기준으로 합니다. point의 message는 중복 키와 원래 값을 포함한 전체 이벤트 JSON 원문을 유지하며, 중복 제거된 JSON으로 원문을 대체하지 않습니다. 마지막으로 유지된 값이 필드 요구 사항을 충족하지 않으면(예: class_uid가 음수) 여전히 잘못된 이벤트로 간주하여 배치 전체에 400을 반환합니다.

아래 단일 이벤트 요청은 변환 검증을 통과하여 1개의 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도 전송하지 않습니다. 예를 들어 {"a.b":1,"a":{"b":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이 전송하는 협상 header 없는 zstd 데이터 패킷과 호환됩니다. 레거시 경로 /v1/tail_sampling_v2는 raw 데이터 패킷만 수신하고, /v2/tail_sampling은 압축 협상 header가 있는 zstd 데이터 패킷을 수신하며, /v1/tail_sampling_config는 테일 샘플링 구성을 수신합니다. 테일 샘플링 기능이 성공적으로 초기화된 경우에만 등록됩니다.
  • 상세 동작 모드, 구성 및 요청 요구 사항은 Dataway 테일 샘플링을 참고하세요.

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

Version-1.17.0

  • API 설명: OpenTelemetry OTLP HTTP/protobuf 데이터를 수신하고 그대로 Kodo의 해당 경로로 포워딩합니다.
  • 지원 경로:
    • POST /otel/v1/traces
    • POST /otel/v1/metrics
    • POST /otel/v1/logs
  • 요청 요구 사항:

    • Content-Type은 반드시 application/x-protobuf여야 하며, media type 파라미터(예: application/x-protobuf; charset=utf-8)를 포함할 수 있습니다.
    • 워크스페이스 token은 token query, X-Token header 또는 Authorization: Bearer <token>으로 전달할 수 있으며, Bearer token은 포워딩 전에 X-Token으로 변환됩니다.
    • OpenTelemetry SDK/Agent 환경 변수를 사용할 때는 OTLP HTTP/protobuf를 명시적으로 구성하고, 기본 endpoint를 Dataway의 /otel 접두사로 설정하는 것이 좋습니다. OpenTelemetry는 시그널에 따라 /v1/traces, /v1/metrics, /v1/logs를 자동으로 추가합니다:
    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
    export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://dataway.example.com/otel/v1/logs
    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://dataway.example.com/otel/v1/traces
    export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://dataway.example.com/otel/v1/metrics
    export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20{token}"
    
    • 시작 파라미터와 환경 변수의 의미는 동일합니다. Java Agent를 예로 들면 -Dotel.exporter.otlp.protocol=http/protobuf, -Dotel.exporter.otlp.endpoint=https://dataway.example.com/otel 및 -Dotel.exporter.otlp.headers=Authorization=Bearer%20{token}을 구성할 수 있습니다. 구현체가 Authorization header의 공백 인코딩 호환성에 차이가 있으면 OTEL_EXPORTER_OTLP_HEADERS="X-Token={token}" 또는 대응하는 시작 파라미터를 사용할 수도 있습니다.
    • Dataway는 OTLP body를 파싱하거나 재작성하지 않습니다. /otel/v1/metrics는 /v1/write/metric line protocol로 변환되지 않으며, Kodo는 DataKit 기본 OTLP metrics 규칙에 따라 파싱합니다. measurement는 otel_service이고, 메트릭 필드 이름은 OTLP 원래 metric name을 유지합니다(예: runtime.jvm.memory는 runtime_jvm_memory로 재작성되지 않음).
    • Kodo가 반환한 원본 OTLP 응답 상태, 응답 body 및 필요한 응답 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이 업로드하는 Profiling 데이터를 수신합니다.

POST /v1/input/firehose

  • API 설명: Firehose 입력 데이터를 수신합니다.

POST /v1/election

  • API 설명: Datakit의 election 요청을 처리합니다.

POST /v1/election/heartbeat

  • API 설명: Datakit의 election 하트비트 요청을 처리합니다.

POST /v1/query/raw

DQL 쿼리 요청을 처리합니다. 간단한 예시는 다음과 같습니다:

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

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

반환 예시:

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

반환 결과 설명:

  • 실제 데이터는 내부의 series 필드에 있습니다.
  • name은 메저먼트 이름을 나타냅니다(여기서는 CPU 메트릭을 조회하며, 로그 유형 데이터라면 해당 필드가 없습니다).
  • columns는 반환된 결과 열 이름을 나타냅니다.
  • values에는 columns에 대응하는 열 결과가 있습니다.

Info
  • URL 요청 파라미터의 token은 JSON body의 token과 다를 수 있습니다. 전자는 쿼리 요청이 유효한지 검증하는 데 사용되고, 후자는 대상 데이터가 위치한 워크스페이스를 결정하는 데 사용됩니다.
  • queries 필드에는 여러 쿼리를 포함할 수 있으며, 각 쿼리는 추가 필드를 포함할 수 있습니다. 구체적인 필드 목록은 여기를 참고하세요.

POST /v1/workspace

  • API 설명: Datakit 측에서 시작한 워크스페이스 조회 요청을 처리합니다.

GET /v1/env_variable

  • API 설명: 워크스페이스 환경 변수를 가져옵니다.

POST /v1/dataway/heartbeat

  • API 설명: Dataway 하트비트 보고 요청을 수신합니다.

POST /v1/object/labels

  • API 설명: 객체 Label 수정 요청을 처리합니다.

DELETE /v1/object/labels

  • API 설명: 객체 Label 삭제 요청을 처리합니다.

GET /v1/check/token/:token

  • API 설명: token이 유효한지 확인합니다.

Langfuse 호환 인터페이스

다음 인터페이스는 Langfuse 클라이언트와의 호환을 위한 것이며, 요청은 업스트림으로 직접 포워딩되고 Dataway는 token 검증을 수행하지 않습니다:

  • POST /api/public/otel/v1/traces: Langfuse OTLP Trace 데이터를 수신합니다.
  • GET /api/public/projects: Langfuse 프로젝트 정보를 가져옵니다.
  • POST /api/public/ingestion: Langfuse ingestion 데이터를 수신합니다. 업스트림은 성공했지만 응답 본문을 반환하지 않은 경우, Dataway는 요청 배치의 이벤트 ID에 따라 Langfuse SDK 4.x 호환 successes/errors JSON 응답을 반환합니다.

Dataway 메트릭 수집

HTTP client 메트릭 수집

Dataway HTTP 요청이 Kodo(또는 다음 홉 Dataway)로 향하는 메트릭을 수집하려면 http_client_trace 구성을 수동으로 활성화해야 합니다. 또는 환경 변수 DW_HTTP_CLIENT_TRACE=true를 지정합니다.

Dataway 자체가 Prometheus 메트릭을 노출하며, Datakit에 내장된 prom 수집기로 해당 메트릭을 수집할 수 있습니다. 수집기 예시 구성은 다음과 같습니다:

[[inputs.prom]]
  ## Exporter URLs.
  urls = [ "http://localhost:9090/metrics", ]
  source = "dataway"
  election = true
  measurement_name = "dw" # dataway 메저먼트는 dw로 고정되며 변경하지 마세요
[inputs.prom.tags]
  service = "dataway"

클러스터에 Datakit이 배포되어 있다면(Datakit 1.14.2 이상 필요) Dataway에서 Prometheus 메트릭 노출을 활성화할 수 있습니다(Dataway 기본 Pod YAML에 이미 포함됨):

annotations: # 아래 annotation은 기본적으로 추가되어 있습니다
   datakit/prom.instances: |
     [[inputs.prom]]
       url = "http://$IP:9090/metrics" # 여기서 포트(기본 9090)는 상황에 따라 다름
       source = "dataway"
       measurement_name = "dw" # 해당 메저먼트로 고정
       interval = "10s"
       disable_instance_tag = true

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

...
env:
- name: DW_PROM_LISTEN
  value: "0.0.0.0:9090" # 여기서 포트는 위 url의 포트와 일치하게 유지

수집에 성공하면 Guance의 「시나리오」/「내장 뷰」에서 dataway를 검색하여 해당 모니터링 뷰를 확인할 수 있습니다.

캐시 및 Kodo 큐 문제 해결

tail_sampling_spill을 활성화하면 전송 실패 시 자체적으로 재시도하며 HTTP 실패 캐시로 들어가지 않습니다. 용량 및 재시도 메트릭은 spill 문제 해결을 참고하세요.

Kodo가 5xx를 반환하거나, Dataway가 Kodo 요청에 실패하거나, Kodo 디스패치 큐가 가득 차면 Dataway는 캐시 가능한 요청을 디스크 캐시에 기록하려고 시도합니다. Kodo 4xx는 캐시에 들어가지 않습니다.

문제 해결 시 다음 메트릭을 우선 확인할 수 있습니다:

  • dataway_http_api_cached_bytes{reason=...}: 요청이 캐시에 기록되었습니다. 일반적인 reason에는 Kodo 5xx 상태 텍스트, httpCliDoFailed 및 kodoQueueFull이 포함됩니다.
  • dataway_http_api_dropped_cache{reason=...}: 요청이 캐시를 시도했지만 기록되지 않았습니다. 일반적인 reason에는 feat-disabled, expected-api-drop, body-md5-not-matched, body-length-not-matched, expired, put-failed 및 sendopt-nil이 포함됩니다.
  • dataway_kodo_queue_full_total{action=...}: Kodo 큐가 가득 찬 후의 처리 결과입니다. action="cache"는 캐시로 전환되었음을 의미하고, action="reject"는 캐시를 사용할 수 없거나 기록 실패 후 503을 반환했음을 의미합니다.
  • dataway_http_concurrency_in_flight / dataway_http_concurrency_waiting: 현재 처리 승인을 받은 요청 수와 여전히 Body를 읽기 전에 대기 중인 요청 수입니다.
  • dataway_http_concurrency_requests_total{result=...}: HTTP 동시성 제한 처리 결과로, admitted, waiting_full, wait_timeout 및 canceled를 포함합니다.

Dataway 메트릭 목록

다음은 Dataway가 노출하는 메트릭입니다. http://localhost:9090/metrics를 요청하여 이러한 메트릭을 가져올 수 있으며, 다음 명령으로 특정 메트릭을 실시간(3s)으로 확인할 수 있습니다:

일부 메트릭을 조회할 수 없는 경우 관련 비즈니스 모듈이 아직 실행되지 않았기 때문일 수 있습니다. 일부 새로운 메트릭은 최신 버전에만 존재합니다. 여기서 각 메트릭의 버전 정보를 더 이상 일일이 표시하지 않으며, /metrics 인터페이스가 반환하는 메트릭 목록을 기준으로 합니다.

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

Docker 모드에서의 메트릭 수집

호스트 설치는 두 가지 모드가 있습니다. 하나는 호스트 머신 설치이고, 다른 하나는 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 자체 Log는 두 가지로 나뉩니다. 하나는 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는 메트릭을 노출하며, 필요 시 일시적으로 profiling 수집 진입점을 활성화하여 문제 해결을 지원할 수 있습니다. pprof는 기본적으로 비활성화되어 있으며, 수집 전에 pprof_bind를 loopback 주소로 명시적으로 설정하고 수집 완료 후 다시 비활성화해야 합니다.

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

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

echo "save bug report to ${br_dir}"

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

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

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

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

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

스크립트 실행:

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

실행이 끝나면 dw-br-1721188604.tar.gz와 유사한 파일이 생성되며, 해당 파일을 꺼내면 됩니다.

FAQ

요청 본문이 너무 큰 문제

Version-1.3.7

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

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

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

  • 메트릭 dataway_http_too_large_dropped_total은 삭제된 대형 요청 수를 노출합니다
  • Dataway 로그에서 cat log | grep 'drop too large request'를 검색하면 로그에 HTTP 요청 Header 상세 정보가 출력되어 클라이언트 상황을 더 자세히 파악할 수 있습니다
Warning

디스크 캐시 모듈에도 최대 데이터 블록 쓰기 제한(기본 64MB)이 있습니다. 최대 요청 본문 구성을 늘리면 이 구성(ENV_DISKCACHE_MAX_DATA_SIZE)도 함께 조정하여 대형 요청이 디스크 캐시에 올바르게 기록되도록 해야 합니다.


  1. 이 제한은 Dataway 컨테이너/Pod 실행 시 시스템 제한으로 인해 약 20000개의 연결만 사용할 수 있는 상황을 방지하기 위한 것입니다. 제한을 늘리면 Dataway 데이터 업로드 효율에 영향을 줄 수 있습니다. Dataway 트래픽이 많을 때는 단일 Dataway의 CPU 수를 늘리거나 Dataway 인스턴스를 수평 확장하는 것을 고려할 수 있습니다. ↩

문서 평가

이 페이지가 도움이 되었나요?