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는 별도의 리스너를 사용하여 운영 체제의 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, 복사 버퍼 메모리가 이보다 크면 메모리 해제
reserved_pool_size: 4096        # 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.19.0
          imagePullPolicy: IfNotPresent
          name: dataway
          ports:
            - containerPort: 9528
              name: 9528tcp01
              protocol: TCP
          resources:
            limits:
              cpu: '4'
              memory: 4Gi
            requests:
              cpu: 100m
              memory: 512Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
          volumeMounts:
            - mountPath: /usr/local/cloudcare/dataflux/dataway/cache
              name: dataway-cache
      dnsPolicy: ClusterFirst
      imagePullSecrets: []
      #nodeSelector:
      #  nodepool: dataway
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
      #tolerations:
      #  - effect: NoSchedule
      #    key: nodepool
      #    operator: Equal
      #    value: dataway
  updateStrategy:
    rollingUpdate:
      partition: 0
    type: RollingUpdate
  volumeClaimTemplates:
    - apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
        name: dataway-cache
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 100Gi
        storageClassName: xxxxxx  # High-Performance Storage StorageClass
        volumeMode: Filesystem
      status:
        phase: Pending

---

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

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

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

• Dataway 설치 확인

설치가 완료된 후 잠시 기다렸다가 '데이터 게이트웨이' 페이지를 새로 고칩니다. 방금 추가한 데이터 게이트웨이의 '버전 정보' 열에 버전 번호가 표시되면 이 Dataway가 Guance 중앙에 성공적으로 연결된 것입니다. 프런트엔드 사용자는 이를 통해 데이터를 수집할 수 있습니다.

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

DataWay 관리¶

DataWay 삭제¶

Guance 관리 백엔드의 '데이터 게이트웨이' 페이지에서 삭제할 DataWay를 선택하고 '구성'을 클릭한 후, 나타나는 DataWay 편집 대화상자에서 왼쪽 하단의 '삭제' 버튼을 클릭합니다.

DataWay 업그레이드¶

Guance 관리 백엔드의 '데이터 게이트웨이' 페이지에서 DataWay에 업그레이드 가능한 버전이 있는 경우 버전 정보에 업그레이드 알림이 표시됩니다.

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

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

Dataway 서비스 관리¶

호스트에 Dataway를 설치한 경우 다음 명령을 사용하여 Dataway 서비스를 관리할 수 있습니다.

# 시작
$ systemctl start dataway

# 재시작
$ systemctl restart dataway

# 중지
$ systemctl stop dataway

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

환경 변수¶

이미지 환경 변수¶

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

HTTP Server 설정¶

HTTP TLS 설정¶

유효 기간이 1년인 TLS 인증서를 생성하려면 다음 OpenSSL 명령을 사용할 수 있습니다:

# 유효 기간 1년 TLS 인증서 생성
$ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out tls.crt -keyout tls.key
...

이 명령을 실행하면 국가, 지역, 도시, 조직 이름, 부서 이름 및 이메일 주소를 포함한 몇 가지 필요한 정보를 입력하라는 메시지가 표시됩니다. 이 정보는 인증서에 포함됩니다.

정보 입력을 완료하면 tls.crt (인증서 파일) 및 tls.key (개인 키 파일) 두 개의 파일이 생성됩니다. 개인 키 파일을 안전하게 보관하십시오.

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

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

GET /v1/ping¶

Version-1.11.0

• API 설명: Dataway의 현재 버전 및 릴리스 날짜를 가져오고 클라이언트 요청의 아웃바운드 IP를 반환합니다.

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

GET /v1/ntp¶

Version-1.6.0

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

POST /v1/write/:category¶

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

POST /v1/aggregate¶

• API 설명: 지표 집계 데이터를 수신합니다. 집계 기능이 초기화에 성공한 경우에만 등록됩니다.
• 자세한 작업 모드, 구성 및 요청 요구 사항은 Dataway 지표 집계를 참조하십시오.

POST /v1/tail_sampling、POST /v1/tail_sampling_v2、POST /v2/tail_sampling 和 POST /v1/tail_sampling_config¶

• API 설명: /v1/tail_sampling은 raw 테일 샘플링 데이터 패킷을 수신하며 Datakit 2.10에서 보내는 협상 헤더가 없는 zstd 데이터 패킷과 호환됩니다. 레거시 경로 /v1/tail_sampling_v2는 raw 데이터 패킷만 수신합니다. /v2/tail_sampling은 압축 협상 헤더가 있는 zstd 데이터 패킷을 수신합니다. /v1/tail_sampling_config는 테일 샘플링 구성을 수신합니다. 테일 샘플링 기능이 초기화에 성공한 경우에만 등록됩니다.
• 자세한 작업 모드, 구성 및 요청 요구 사항은 Dataway 테일 샘플링을 참조하십시오.

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

Version-1.17.0

• API 설명: OpenTelemetry OTLP HTTP/protobuf 데이터를 수신하고 Kodo 해당 경로로 원본 그대로 전달합니다.
• 지원 경로:
  • POST /otel/v1/traces
  • POST /otel/v1/metrics
  • POST /otel/v1/logs

• 요청 요구 사항:

  • Content-Type은 반드시 application/x-protobuf여야 하며, 미디어 타입 매개변수(예: application/x-protobuf; charset=utf-8)를 포함할 수 있습니다.
  • 공간 토큰은 token query, X-Token header 또는 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 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 원래 지표 이름을 유지합니다(예: 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의 선출 heartbeat 요청을 처리합니다

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 heartbeat 보고 요청을 수신합니다.

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 모드에서의 지표 수집¶

호스트 설치는 두 가지 모드가 있습니다. 하나는 호스트 OS에 직접 설치하는 것이고, 다른 하나는 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 또는 제어된 포트 포워딩을 통해 수집할 수 있습니다. loopback이 아닌 주소로 구성하면 거부됩니다.

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를 loopback 주소로 명시적으로 설정하고 수집이 완료된 후 다시 비활성화해야 합니다.

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

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 세부 정보를 출력하여 클라이언트 상황을 더 잘 이해할 수 있도록 합니다