LoongSuite
LoongSuite 오픈 소스 버전은 Go 애플리케이션의 트레이스 데이터를 OpenTelemetry OTLP 프로토콜을 통해 수집기로 전송할 수 있습니다. DataKit는 OpenTelemetry 수집기를 사용해 LoongSuite가 보고한 트레이스 데이터를 수신할 수 있으며, 별도의 전용 수집기를 활성화할 필요가 없습니다.
LoongSuite를 연동하기 전에 DataKit에서 OpenTelemetry 수집기가 활성화되어 있는지 확인하고, 사용하는 OTLP 프로토콜에 따라 gRPC 또는 HTTP/protobuf 연동 방식을 선택하세요.
설정¶
DataKit 설정¶
DataKit 설치 디렉터리의 conf.d/samples 디렉터리로 이동해 opentelemetry.conf.sample을 복사한 뒤 opentelemetry.conf로 이름을 바꾸고, gRPC 또는 HTTP 수신 설정이 활성화되어 있는지 확인합니다.
OpenTelemetry 수집기의 기본 수신 주소는 다음과 같습니다.
| 프로토콜 | 주소 |
|---|---|
gRPC |
http://<datakit-host>:4317 |
HTTP/protobuf |
http://<datakit-host>:9529/otel/v1/traces |
설정이 완료되면 DataKit를 재시작합니다.
LoongSuite 설정¶
트레이스 데이터를 gRPC 프로토콜로 전송하는 것을 권장합니다.
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<datakit-host>:4317
export OTEL_SERVICE_NAME=<service-name>
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,service.version=1.0.0
HTTP/protobuf 프로토콜을 사용하는 경우, Trace endpoint를 DataKit OpenTelemetry 수집기의 기본 경로로 명시적으로 설정해야 합니다.
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://<datakit-host>:9529/otel/v1/traces
export OTEL_SERVICE_NAME=<service-name>
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,service.version=1.0.0
Warning
DataKit OpenTelemetry 수집기의 HTTP Trace 기본 경로는 /otel/v1/traces입니다. LoongSuite 또는 OpenTelemetry SDK가 기본 OTLP HTTP 경로 /v1/traces를 사용하는 경우, LoongSuite 측에서 endpoint를 명시적으로 조정해야 합니다.
필드 매핑¶
LoongSuite가 보고한 OTLP span attributes는 OpenTelemetry 수집기가 고정된 태그 목록에 따라 추출합니다. 일반적인 필드 매핑은 다음과 같습니다.
| 원본 필드 | DataKit 필드 |
|---|---|
db.system |
db_system |
db.system.name |
db_system |
db.operation |
db_operation |
db.operation.name |
db_operation |
db.query.text |
db_statement |
db.namespace |
db_name |
db.collection.name |
db_collection |
http.request.method |
http_method |
http.response.status_code |
http_status_code |
network.protocol.name |
net_protocol_name |
network.protocol.version |
net_protocol_version |
network.local.address |
network_local_address |
network.local.port |
network_local_port |
user_agent.original |
user_agent_original |
messaging.system |
messaging_system |
messaging.operation.name |
messaging_operation |
messaging.operation.type |
messaging_operation_type |
messaging.message.id |
messaging_message_id |
rpc.system.name |
rpc_system |
rpc.method |
rpc_method |
rpc.grpc.status_code |
rpc_grpc_status_code |
LoongSuite가 보고한 사용자 정의 attributes를 추출해야 하는 경우, opentelemetry.conf에서 customer_tags를 설정할 수 있습니다. customer_tags는 정규식을 지원하며, 일치한 필드는 태그로 승격되고 필드명에 포함된 .은 _로 대체됩니다.
[[inputs.opentelemetry]]
customer_tags = [
"reg:^db\\.query\\.parameter\\.",
"reg:^kratos\\.service\\.meta\\.",
"reg:^gen_ai\\.other_input\\.",
"reg:^gen_ai\\.other_output\\.",
]
데이터 보기¶
설정이 완료되면 LoongSuite가 연동된 Go 애플리케이션을 시작하고 요청을 발생시킵니다. 트레이스 데이터는 DataKit OpenTelemetry 수집기로 들어가며,Guance 플랫폼의 트레이스 뷰어에서 service.name 기준으로 표시됩니다.
트레이스가 보고되지 않으면 우선 다음 사항을 확인하세요.
- DataKit OpenTelemetry 수집기가 활성화되어 있고 재시작 후 반영되었는지;
- LoongSuite OTLP exporter의 프로토콜과 endpoint가 DataKit 수신 설정과 일치하는지;
HTTP/protobuf를 사용할 때 Trace endpoint가/otel/v1/traces인지;OTEL_SERVICE_NAME또는service.name이 설정되어 있는지.