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 듀얼 스택을 지원하는지 확인한 후 다음 구성을 동시에 수정하세요:
- Dataway 컨테이너 환경 변수에서
DW_BIND_IPV6의 주석을 해제하고[::]:9528로 설정하여 Dataway가 IPv4와 IPv6를 동시에 리슨하도록 합니다. - 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로 마운트해야 합니다:
컨테이너 설치에 필요한 환경 변수는 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에 업그레이드 가능한 버전이 있으면 버전 정보에 업그레이드 안내가 표시됩니다.
Dataway 서비스 관리¶
호스트에 Dataway를 설치한 경우 다음 명령으로 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가 적용되었는지 테스트할 수 있습니다:
성공하면 It's working! ASCII Art 정보가 표시됩니다. 인증서가 없으면 Dataway 로그에 다음과 유사한 오류가 표시됩니다:
이때 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을 설정하면 디스크 캐시를 비활성화할 수 있습니다.
성능 관련 설정¶
| Env | 설명 |
|---|---|
| DW_COPY_BUFFER_DROP_SIZE type: int required: N |
지정 크기(단위 바이트)를 초과하는 단일 HTTP body buffer는 즉시 지워 메모리 소비를 줄입니다. 기본값 256KB |
Dataway API 목록¶
진단 및 로컬 처리 인터페이스를 제외하고, 포워딩类 인터페이스는 각자의 token 검증 규칙에 따라 요청을 Kodo 또는 다음 홉 Dataway로 포워딩합니다. Langfuse 호환 인터페이스의 인증 동작은 후문을 참고하세요.
GET /v1/ping¶
- API 설명: Dataway의 현재 버전 번호와 릴리스 날짜를 가져오며, 동시에 클라이언트 요청의 출구 IP를 반환합니다.
DataWay가 404 페이지를 비활성화한 경우(
disable_404page), 이 인터페이스는 서비스를 제공할 수 없습니다.
GET /v1/ntp¶
- 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또는DatasetEventJSON을 수신하고 요청을 그대로 Kodo 또는 다음 홉 Dataway로 포워딩합니다. - 요청 요구 사항:
Content-Type은 반드시application/json이어야 하며, media type 파라미터(예:application/json; charset=utf-8)를 포함할 수 있습니다.- 워크스페이스 token은
tokenquery,X-Tokenheader 또는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를 저장하며, querytoken과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}¶
- API 설명: OpenTelemetry OTLP HTTP/protobuf 데이터를 수신하고 그대로 Kodo의 해당 경로로 포워딩합니다.
- 지원 경로:
POST /otel/v1/tracesPOST /otel/v1/metricsPOST /otel/v1/logs
-
요청 요구 사항:
Content-Type은 반드시application/x-protobuf여야 하며, media type 파라미터(예:application/x-protobuf; charset=utf-8)를 포함할 수 있습니다.- 워크스페이스 token은
tokenquery,X-Tokenheader 또는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}을 구성할 수 있습니다. 구현체가Authorizationheader의 공백 인코딩 호환성에 차이가 있으면OTEL_EXPORTER_OTLP_HEADERS="X-Token={token}"또는 대응하는 시작 파라미터를 사용할 수도 있습니다. - Dataway는 OTLP body를 파싱하거나 재작성하지 않습니다.
/otel/v1/metrics는/v1/write/metricline 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/errorsJSON 응답을 반환합니다.
Dataway 메트릭 수집¶
HTTP client 메트릭 수집
Dataway HTTP 요청이 Kodo(또는 다음 홉 Dataway)로 향하는 메트릭을 수집하려면 http_client_trace 구성을 수동으로 활성화해야 합니다. 또는 환경 변수 DW_HTTP_CLIENT_TRACE=true를 지정합니다.
Dataway 자체가 Prometheus 메트릭을 노출하며, Datakit에 내장된 prom 수집기로 해당 메트릭을 수집할 수 있습니다. 수집기 예시 구성은 다음과 같습니다:
클러스터에 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인터페이스가 반환하는 메트릭 목록을 기준으로 합니다.
| 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 주소로 명시적으로 설정하고 수집 완료 후 다시 비활성화해야 합니다.
다음 정보 수집은 실제 구성된 포트와 주소를 기준으로 합니다.
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}
스크립트 실행:
실행이 끝나면 dw-br-1721188604.tar.gz와 유사한 파일이 생성되며, 해당 파일을 꺼내면 됩니다.
FAQ¶
요청 본문이 너무 큰 문제¶
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)도 함께 조정하여 대형 요청이 디스크 캐시에 올바르게 기록되도록 해야 합니다.
-
이 제한은 Dataway 컨테이너/Pod 실행 시 시스템 제한으로 인해 약 20000개의 연결만 사용할 수 있는 상황을 방지하기 위한 것입니다. 제한을 늘리면 Dataway 데이터 업로드 효율에 영향을 줄 수 있습니다. Dataway 트래픽이 많을 때는 단일 Dataway의 CPU 수를 늘리거나 Dataway 인스턴스를 수평 확장하는 것을 고려할 수 있습니다. ↩