네트워크 경로

NetPath 수집기는 DataKit가 실행 중인 노드에서 대상의 네트워크 경로를 능동적으로 탐지하며, TCP, UDP, ICMP를 지원합니다. 대상은 정적 설정으로 지정할 수도 있고 datakit-ebpf 같은 로컬 트래픽 소스에서 동적으로 발견할 수도 있습니다. NetPath는 현재 Linux와 macOS를 지원하며, Windows는 아직 지원하지 않습니다.

매 실행마다 네트워크(N) 분류의 netpath 데이터 1개가 생성되며, 여기에는 소스 및 대상 컨텍스트, 엔드투엔드 지연, ICMP 패킷 손실 지표, 여러 번의 traceroute에 대한 홉별 결과가 포함됩니다.

설정¶

[[inputs.netpath]]
  ## 정적 대상의 기본 프로토콜: tcp/udp/icmp/auto.
  protocol = "tcp"

  ## 정적 대상 probe의 기본 간격.
  interval = "60s"

  ## 각 probe의 타임아웃.
  timeout = "1s"

  ## 독립적인 엔드투엔드 probe. 중간 홉은 검사하지 않습니다.
  e2e_queries = 10

  ## 최대 traceroute TTL과 전체 traceroute 실행 횟수.
  ## 유효 TTL 상한은 TCP/ICMP는 60, Linux UDP는 255입니다.
  max_ttl = 30
  traceroute_queries = 3

  ## 정적 네트워크 경로 대상.
  # [[inputs.netpath.targets]]
  #   name = "api-gateway"
  #   target = "api.example.com"
  #   port = 443
  #   protocol = "tcp"
  #   interval = "60s"
  #   timeout = "1s"
  #   max_ttl = 30
  #   traceroute_queries = 3
  #   e2e_queries = 10
  #   [inputs.netpath.targets.tags]
  #     service = "api"

  ## datakit-ebpf 같은 로컬 트래픽 소스에서 발견된 동적 대상.
  [inputs.netpath.dynamic]
    enabled = true
    ## 클라이언트와 수락한 서버 주소가 모두 loopback일 때만 선택적으로 필요합니다.
    ## 그 외 모든 요청에는 토큰이 필요합니다.
    ## datakit-ebpf에도 동일한 토큰을 설정하세요. 이 토큰은 다음 헤더로 전송됩니다:
    ## X-Datakit-Netpath-Token: <token>
    token = ""

    ## auto/tcp/udp/icmp. auto는 후보 프로토콜을 사용하고,
    ## 포트가 있는 후보는 tcp로, 주소만 있는 후보는 icmp로 폴백합니다.
    ## Traceroute에는 raw socket 권한이 필요합니다. UDP traceroute는 Linux에서 지원됩니다.
    protocol = "auto"

    ## 동적 후보는 중복 제거되어 ttl 동안 유지됩니다. 스케줄러는
    ## 후보가 살아 있는 동안 interval마다 각 후보를 실행합니다.
    contexts_limit = 5000
    ## 저장된 컨텍스트와 현재 실행 중인 컨텍스트의 총 추정 보존 바이트 수.
    contexts_bytes_limit = 67108864
    ttl = "50m"
    interval = "20m"
    flush_interval = "10s"
    max_per_minute = 150
    workers = 4
    timeout = "1s"
    ## 유효 TTL 상한은 TCP/ICMP는 60, Linux UDP는 255입니다.
    max_ttl = 30
    traceroute_queries = 3
    e2e_queries = 10
    ## 저장소 잠금을 기다리는 최대 동시 후보 수락 요청 수.
    input_queue = 1000
    process_queue = 1000
    max_tests_per_request = 1000
    max_body_bytes = 1048576

    ## 도메인이나 호스트명을 포함하지 않는 주소만의 후보를 허용하려면 true로 설정하세요.
    ## false로 유지하면 고카디널리티 경로 테스트 잡음을 줄일 수 있습니다.
    monitor_ip_without_domain = false

    ## 후보 제외 규칙. 한 규칙 안의 조건은 AND로 결합되며, 같은 조건의 값은 OR로 결합됩니다.
    ## 어떤 규칙과도 일치하는 후보는 스케줄러에 들어가기 전에 제외됩니다.
    ## 호스트명 대상은 매 DNS 조회 후와 probe 패킷 전송 전, 목적지 host/CIDR 규칙과 다시 검사됩니다.
    # [[inputs.netpath.dynamic.filters]]
    #   name = "ignore-kube-system"
    #   namespaces = ["kube-system"]
    #
    # [[inputs.netpath.dynamic.filters]]
    #   name = "ignore-private-db"
    #   dest_cidrs = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
    #   ports = [5432, 6379]

  ## 목적지 및 홉 IP에 대한 선택적 reverse DNS 보강. 모든 traceroute 결과에 DNS 조회 지연이
  ## 추가되는 것을 피하기 위해 기본값은 비활성화되어 있습니다.
  [inputs.netpath.reverse_dns]
    enabled = false
    timeout = "500ms"
    cache_ttl = "10m"
    cache_size = 4096

  [inputs.netpath.tags]
    # some_tag = "some_value"

정적 대상¶

[[inputs.netpath.targets]]로 정적 대상을 설정합니다:

[[inputs.netpath.targets]]
  name = "api-gateway"
  target = "api.example.com"
  port = 443
  protocol = "tcp"
  interval = "60s"
  timeout = "1s"
  max_ttl = 30
  traceroute_queries = 3
  e2e_queries = 10

  [inputs.netpath.targets.tags]
    service = "api"

프로토콜이 auto일 때, 포트가 있는 대상은 TCP를 사용하고 포트가 없는 대상은 ICMP를 사용합니다. UDP는 현재 Linux에서만 지원되며, DataKit가 raw ICMP 응답을 수신할 수 있는 권한이 필요합니다. TCP/ICMP traceroute의 유효 max_ttl 상한은 60이며, Linux UDP traceroute의 상한은 255입니다.

traceroute_queries는 전체 traceroute 실행 횟수를 의미합니다. 매 실행은 TTL 1부터 대상 또는 max_ttl까지 독립적으로 탐지하며, 같은 TTL에서 여러 번 재시도하는 대신 message.runs[] 요소 하나를 생성합니다. 대상이 도메인일 경우 각 run은 독립적으로 DNS 해석을 수행하며, 실제 대상 IP는 runs[].destination.ip_address에 기록되고 한 번의 작업이 도메인의 모든 IP를 모두 포함한다고 보장하지 않습니다.

e2e_queries는 독립적인 엔드투엔드 probe 횟수를 의미하며 기본값은 10입니다. E2E는 중간 hop을 검사하지 않으며 traceroute와 병렬로 실행됩니다. TCP는 연결 응답을 사용하고, ICMP는 Echo Reply를 사용하며, Linux UDP는 목적지 ICMP 응답을 사용합니다. E2E 발송은 traceroute의 max_ttl을 사용하지 않고 정상적인 엔드투엔드 IP TTL을 사용합니다. 도메인은 E2E를 위해 별도로 해석되며, 선택된 주소는 e2e_dest_ip에 기록되고 message.runs[].destination.ip_address와 다를 수 있습니다. UDP 애플리케이션의 무응답은 e2e_unknown으로 기록되며, 곧바로 패킷 손실로 간주되지 않습니다.

동적 대상¶

동적 대상 API의 기본값은 POST /v1/netpath/candidates입니다. dynamic.enabled는 기본적으로 활성화되어 있습니다. DataKit HTTP 리스닝 주소가 호스트 외부로 노출될 수 있다면 반드시 비어 있지 않은 dynamic.token을 설정해야 하며, 요청자는 X-Datakit-Netpath-Token 요청 헤더에 같은 토큰을 포함해야 합니다.

동적 후보는 hostname이 있으면 hostname 기준으로 중복 제거 및 탐지하고, 없으면 IP를 사용하며, ttl 수명 동안 interval 주기로 실행됩니다. 같은 비 NAT hostname의 서로 다른 관측 IP는 하나의 스케줄 작업을 공유합니다. 목적지 주소 변환이 발생하면 원본 목적지 IP와 포트가 추가로 작업 식별에 사용됩니다. 동적 작업의 context, 큐, 속도, worker 제한은 이미 설정된 정적 대상을 점유하거나 삭제하지 않습니다. monitor_ip_without_domain = false를 유지하고, 트래픽을 확대하기 전에 dynamic.filters로 탐지할 필요가 없는 namespace, 대역, 포트를 제외하여 고카디널리티 경로가 생기지 않도록 하는 것을 권장합니다.

hostname 후보의 경우 매 DNS 해석 후, traceroute 또는 E2E 발송 전마다 해석 결과를 사용해 목적지 host 및 CIDR 필터 규칙을 다시 검사합니다. 후보 식별자 필드는 개별 항목당 최대 1024 bytes이며, 요청 수준 기본값을 포함해 각 test의 식별자 필드 합계는 최대 4096 bytes입니다. 각 후보의 요청 수준 tags와 test 수준 tags의 합계는 최대 64개이며, tag key는 최대 128 bytes, value는 최대 1024 bytes입니다. 고정 프로토콜 필드(예: traceroute_status, traceroute_fail_type, 엔드포인트 4-tuple)는 사용자 정의 tags로 덮어쓸 수 없습니다.

datakit-ebpf의 동적 발견을 사용하려면 eBPF 수집기에서도 다음을 활성화해야 합니다:

[inputs.ebpf]
  network_path_enabled = true
  network_path_api = "http://127.0.0.1:9529/v1/netpath/candidates"
  network_path_token = ""

역방향 DNS¶

역방향 DNS는 기본적으로 꺼져 있습니다. 활성화하면 DataKit는 목적지 IP와 응답이 있는 hop IP에 대해 PTR 조회를 수행하고, TTL 캐시로 반복 조회를 제한합니다:

[inputs.netpath.reverse_dns]
  enabled = true
  timeout = "500ms"
  cache_ttl = "10m"
  cache_size = 4096

데이터 구조¶

하나의 결과에서 tags는 작업, 소스, 목적지, 경로를 필터링하는 데 사용되며, 주요 항목은 다음과 같습니다:

• 작업: task_name, task_source, origin, run_type, protocol;
• 4-tuple: src_ip, src_port, dst_ip, dst_port, DNAT가 발생한 경우 dst_nat_ip, dst_nat_port 추가;
• 엔드포인트 컨텍스트: dst_domain, source_host, source_service, source_process, source_container_id, src_cloud_provider, dst_cloud_provider;
• 실제 probe 출구: probe_source_ip, probe_gateway_ip, probe_interface, probe_netns;
• 상태: traceroute_protocol, traceroute_status, traceroute_fail_type, e2e_status.

소스와 목적지 tags는 홉별 결과에 의존하지 않습니다. 4-tuple 명명은 NetFlow와 맞춥니다. dst_*는 원본 목적지를 의미하고, dst_nat_*는 실제 탐지에 사용된 DNAT 이후 목적지를 의미합니다. 알 수 없는 포트는 "*"를 사용합니다. probe가 hop을 생성하지 못했더라도 최상위 엔드포인트는 여전히 조회에 사용할 수 있습니다. 엔드포인트의 *_cloud_provider는 선택적 클라우드 제공자 정보입니다.

NetPath는 branch_key나 path_key를 업로드하지 않습니다. 과거 기록은 위의 구조화된 작업, 소스, 목적지 tags로 조회해야 하며, 실제 라우팅 분기와 그 변화는 message.runs[].hops[]에서 계산합니다.

경로 완료 상태는 traceroute_status(reached, partial, failed)를 사용합니다. 이는 traceroute가 목적지에 도달했는지 설명할 뿐, 엔드투엔드 품질을 의미하지는 않습니다.

엔드투엔드 품질은 독립적인 e2e_* 필드로 통일해서 사용합니다:

• e2e_dest_ip：E2E probe가 독립적으로 해석하여 실제 사용한 IPv4 주소；
• e2e_packets_sent, e2e_packets_received, e2e_unknown：probe 전송 수, 응답 수, 불확실한 결과 수；
• e2e_probe_loss_percent：명확한 응답이 없는 결정적 probe의 비율이며, 불명확한 UDP 무응답은 분모에 포함되지 않음；
• e2e_rtt_avg, e2e_rtt_min, e2e_rtt_max：엔드투엔드 RTT, 단위는 마이크로초；
• e2e_rtt_variation_avg, e2e_rtt_variation_max：전송 순서상 인접한 성공 probe 간 RTT의 절대 차이, 단위는 마이크로초。

프런트엔드는 e2e_rtt_avg로 경로 전체 지연을 표시하고, e2e_probe_loss_percent로 엔드투엔드 probe 무응답 비율을 표시해야 합니다. e2e_status와 traceroute_status는 서로 독립적입니다. TCP connection refused/RST는 목적지 도달을 증명하므로 received에 포함됩니다. e2e_probe_loss_percent는 어떤 중간 장비의 실제 패킷 손실률이 아닙니다.

홉별 경로¶

전체 경로는 message field에 표준 JSON으로 기록됩니다:

{
  "runs": [
    {
      "run_id": "1",
      "destination": {
        "ip_address": "8.8.8.8",
        "port": 443,
        "reverse_dns": ["dns.google"]
      },
      "hops": [
        {
          "ttl": 1,
          "ip_address": "10.0.0.1",
          "reverse_dns": ["gateway.local"],
          "rtt": 0.8315,
          "reachable": true
        },
        {
          "ttl": 2,
          "reachable": false
        },
        {
          "ttl": 3,
          "ip_address": "8.8.8.8",
          "rtt": 12.45,
          "reachable": true,
          "asn": 15169,
          "as_name": "GOOGLE",
          "as_prefix": "8.8.8.0/24",
          "cloud_provider": "gcp"
        }
      ]
    }
  ],
  "hop_count": {
    "avg": 3,
    "min": 3,
    "max": 3
  }
}

필드 설명:

ASN과 클라우드 제공자 필드는 서버 측 선택적 보강에 해당합니다. 사설망, CGNAT, 무응답 hop, 데이터베이스 누락, 매칭 실패 시에는 해당 필드가 나타나지 않습니다. 보강 과정에서 제3자 서비스로 hop IP를 전송하지 않으며, as_name만 보고 클라우드 제공자를 추측하지도 않습니다.

탐지가 경로를 생성하기 전에 실패하면 message는 JSON이 아니라 오류 텍스트일 수 있으므로, traceroute_status=failed, traceroute_fail_type, traceroute_fail_reason와 함께 처리해야 합니다.

로그¶

netpath¶

보안 및 개인정보¶

• DataKit는 NetPath 결과와 함께 traceroute에서 관측된 hop IP를 업로드하며, 이는 경로 표시의 기본 데이터입니다.
• DataKit는 hop IP를 외부 ASN 조회 서비스로 전송하지 않습니다. ASN은 Kodo 내부에서 오프라인 데이터베이스로 보강합니다.
• Reverse DNS는 DataKit가 있는 네트워크 안에서 DNS 조회를 수행합니다. DNS 노출이 민감하다면 꺼둬야 합니다.
• 원본 hop IP가 고객 네트워크 밖으로 나가면 안 된다면 배포 전에 NetPath 활성화 여부를 평가해야 합니다. ASN 보강만 Kodo로 옮겨도 관측 플랫폼에 업로드되는 원본 IP는 숨겨지지 않습니다.

문제 해결¶