ddtrace 일반 매개변수 사용법¶
작성자: 刘锐
전제 조건¶
-
시작 명령어
java -javaagent:D:/ddtrace/dd-java-agent-guance.jar \
-Ddd.service.name=ddtrace-server \
-Ddd.agent.port=9529 \
-jar springboot-ddtrace-server.jar
매개변수 사용¶
쿼리 매개변수 활성화¶
쿼리 매개변수를 활성화하면 사용자가 현재 요청에 어떤 매개변수가 포함되어 있는지 더 직관적으로 확인할 수 있으며, 실제 사용자 작업 흐름을 더 정확하게 재현할 수 있습니다. 기본값은 false이며, 기본적으로 활성화되지 않음을 의미합니다.
단, 쿼리 활성화 매개변수는 URL의 매개변수만 수집할 수 있으며, Request Body 내의 매개변수는 현재 지원되지 않습니다.
원격 수집 연결 구성¶
dd.agent.host의 기본값은 localhost이므로 기본적으로 로컬 DataKit으로 전송됩니다.
원격 DataKit으로 전송하려면 dd.agent.host를 구성해야 합니다.
태그 추가 두 가지 방법¶
ddtrace는 두 가지 태그 추가 방법을 제공하며, 효과는 동일합니다. 그러나 dd.tags 방식을 권장합니다.
1. dd.trace.span.tags¶
각 스팬에 projectName:observable-demo를 추가하는 예시:
2. dd.tags¶
위 두 가지 방법 모두 태그를 생성할 수 있으며, 효과는 동일하고 meta 내에 데이터가 표시됩니다.
dd.tags로 표시된 태그를 Guance의 태그로 사용하려면 ddtrace.conf에서 customer_tags를 구성해야 합니다.
[[inputs.ddtrace]]
endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]
customer_tags = ["projectName","user_name"]
효과는 다음과 같습니다:
데이터베이스 인스턴스 이름 표시¶
데이터베이스의 이름을 표시합니다. 기본적으로 데이터베이스 유형이 표시됩니다. 데이터베이스 이름을 표시하려면 값을 TRUE로 설정하세요.
위 데모에는 데이터베이스가 로드되지 않았습니다. 따라서 이 효과를 얻으려면 데이터베이스를 도입한 애플리케이션을 선택하여 매개변수를 추가하세요.
효과는 다음과 같습니다:
클래스 또는 메서드에 트레이스 주입¶
ddtrace는 메서드에 트레이스를 주입하는 것을 지원합니다. 기본적으로 ddtrace는 모든 API 엔드포인트에 자동으로 트레이스를 주입합니다.
비 API 클래스(메서드) — 즉, 중요한 클래스나 메서드에 대해 특별히 표시하려면 dd.trace.methods 매개변수를 통해 구성할 수 있습니다.
- 환경 변수: DD_TRACE_METHODS
- 기본값: null
- 예시: package.ClassName[method1,method2,...];AnonymousClass$1[call];package.ClassName[*]
트레이스를 적용할 클래스/인터페이스 및 메서드 목록. @Trace를 추가하는 것과 유사하지만, 코드를 변경할 필요가 없습니다. - 참고: 와일드카드 메서드 지원([*])은 생성자, getter, setter, synthetic, toString, equals, hashcode, finalizer 메서드 호출을 포함하지 않습니다.
예를 들어 com.zy.observable.ddtrace.service.TestService 클래스의 getDemo 메서드에 트레이스를 추가해야 하는 경우:
관련 코드 일부:
@Autowired
private TestService testService;
@GetMapping("/gateway")
@ResponseBody
public String gateway(String tag) {
String userId = "user-" + System.currentTimeMillis();
MDC.put(ConstantsUtils.MDC_USER_ID, userId);
logger.info("this is tag");
sleep();
testService.getDemo();
httpTemplate.getForEntity(apiUrl + "/resource", String.class).getBody();
httpTemplate.getForEntity(apiUrl + "/auth", String.class).getBody();
if (client) {
httpTemplate.getForEntity("http://"+extraHost+":8081/client", String.class).getBody();
}
return httpTemplate.getForEntity(apiUrl + "/billing?tag=" + tag, String.class).getBody();
}
dd.trace.methods 매개변수를 추가하지 않은 경우 11개의 스팬이 보고됩니다. 효과는 다음과 같습니다:
헤더를 통한 사용자 정의 비즈니스 태그¶
주로 헤더 방식을 통해 비침입적으로 비즈니스 태그를 트레이스에 주입하여 해당 비즈니스의 실행 상태를 추적할 수 있습니다. Key:value 방식으로 구성하며, key는 원본 헤더의 paramName이고, value는 key의 이름 변경입니다. key는 생략할 수 있습니다.
요청
트레이스 효과:
배기지, 태그 무제한 투과 전파¶
환경 변수: DD_TRACE_HEADER_BAGGAGE
기본값: null
예시: CASE-insensitive-Header:my-baggage-name,User-ID:userId,My-Header-And-Baggage-Name
예시:
-Dd.trace.header.tags는 투과 전파 기능을 제공하지 않습니다. 배기지는 헤더 태그를 무제한으로 투과 전파할 수 있습니다.
트레이스 효과:
디버그 모드 활성화¶
디버그 모드를 활성화하면 시스템에서 ddtrace 관련 로그를 출력하여 ddtrace 문제를 진단하는 데 도움이 됩니다.
기본적으로 디버그 로그는 stdout으로 출력됩니다. 파일로 출력하려면 다음 매개변수를 함께 사용해야 합니다.
참고
-Dd.trace.debug=true는 ddtrace의 디버그 로그를 활성화하는 것이며, 애플리케이션의 디버그 로그를 활성화하는 것이 아닙니다.
traceId 128비트 활성화¶
traceId는 기본적으로 64비트(long형)입니다. opentelemetry(traceId 128비트)와의 호환성을 높이기 위해 수동으로 128비트를 활성화할 수 있습니다.
트레이스 정보 출력¶
개발 관련 작업이 필요할 경우, 트레이스 보고 데이터 구조를 이해하는 것이 유용합니다. 기본적으로 트레이스 정보는 DDAgentWriter를 통해 원격 관측 가능성 플랫폼으로 보고됩니다. 콘솔에 해당 정보를 출력하려면 다음 매개변수를 구성할 수 있습니다:
여러 개를 구성할 수도 있습니다:
서비스 이름으로 미들웨어 이름 대체 활성화¶
기본적으로 트레이스 정보는 미들웨어 이름별로 그룹화되어 표시됩니다. 따라서 애플리케이션에 미들웨어에서 생성된 트레이스 정보만 있는 경우, 현재 미들웨어가 속한 애플리케이션을 추적할 수 없습니다. 전역 태그 서비스 이름을 미들웨어의 서비스로 사용하도록 매개변수를 조정할 수 있습니다. 다음 매개변수로 구성합니다:
시작 매개변수 방식으로 주입:
환경 변수 방식으로 주입:
위 두 가지 방식 중 하나를 선택하세요.
최종 효과: 미들웨어 서비스 이름이 더 이상 표시되지 않습니다(즉, 애플리케이션 서비스 이름이 미들웨어 이름을 대체함). 스팬의 다른 태그와 데이터는 영향을 받지 않습니다.
대체 전 효과:
대체 후 효과:
전파자 구성¶
ddtrace는 다음과 같은 전파자를 지원합니다. 전파자 유형은 대소문자를 구분하지 않습니다.
- Datadog : 기본 전파자
- B3 : B3 전파는 헤더 "b3" 및 "x-b3-"로 시작하는 헤더의 사양입니다. 이러한 헤더는 서비스 경계를 넘는 트레이스 컨텍스트 전파에 사용됩니다. B3에는 두 가지 방식이 있습니다:
- B3SINGLE(B3_SINGLE_HEADER), 헤더 키는
b3입니다. - B3(B3MULTI), 헤더 키는
x-b3-입니다.
- B3SINGLE(B3_SINGLE_HEADER), 헤더 키는
- haystack
- tracecontext: 기본 전파자
- xray : AWS 전파자
또는 환경 변수 구성:
ddtrace 1.9.0 이전 버전에서는 다음을 사용합니다:
또는참고: 여러 전파자를 구성할 수 있으며, 여러 전파자는 ,로 구분합니다. 전파자 유형은 대소문자를 구분하지 않습니다.
전파자에 대한 자세한 내용은 링크 전파(Propagate) 메커니즘 및 사용 사례를 참조하세요.
응답에서 TraceId 반환¶
이 항목은 추가 구성이 필요하지 않습니다. 요청 응답이 완료되면 키가 guance_trace_id인 헤더가 추가됩니다.
version >= 1.25.1-guance
헤더 태그¶
요청 및 응답의 모든 헤더를 트레이스 태그에 추가합니다. 요청 헤더의 태그 이름은 request_header, 응답 헤더의 태그 이름은 response_header입니다. 다음 두 가지 방식 중 하나를 선택하여 활성화합니다:
- 시작 명령어
-Dd.trace.headers.enabled: 기본값은 false이며, 활성화되지 않음을 의미합니다.
- 환경 변수
DD_TRACE_HEADERS_ENABLED
| 컴포넌트 | ddtrace 버전 |
|---|---|
| javax.servlet | >=1.25 |
| jakarta.servlet | >=1.42.9 |
Request body 태그¶
요청 본문을 트레이스 태그에 추가합니다. 현재 POST 요청만 지원하며, Context-Type이 application/json 또는 application/json;charset=UTF-8인 경우에만 해당됩니다.
- 시작 명령어
-Dd.trace.request.body.enabled: 기본값은 false이며, 활성화되지 않음을 의미합니다.
- 환경 변수
DD_TRACE_REQUEST_BODY_ENABLED
다음 요청을 실행하는 경우:
curl -X POST -H 'Content-Type: application/json' -d '{"username":"joy","age":18}' http://localhost:8090/jsonStr
| 컴포넌트 | ddtrace 버전 |
|---|---|
| javax.servlet | >=1.25 |
| jakarta.servlet | >=1.42.9 |
Response body 태그¶
응답 본문의 내용을 트레이스 태그에 추가합니다. application/json 및 text/plain 유형의 데이터를 지원합니다.
- 시작 명령어
-Dd.trace.response.body.enabled: 기본값은 false이며, 활성화되지 않음을 의미합니다.
- 환경 변수
DD_TRACE_RESPONSE_BODY_ENABLED
response body를 읽으면 일정량의 Java 메모리 공간을 차지합니다. 응답 본문이 큰 요청(예: 파일 다운로드 API)의 경우 OOM을 방지하기 위해 블랙리스트 처리를 추가하는 것이 좋습니다. 블랙리스트에 있는 URL은 응답 본문을 더 이상 파싱하지 않습니다.
블랙리스트 구성은 다음과 같습니다:
- 매개변수 방식
-Dd.trace.response.body.blacklist.urls="/auth,/download/file"
- 환경 변수 방식
DD_TRACE_RESPONSE_BODY_BLACKLIST_URLS
| 컴포넌트 | ddtrace 버전 |
|---|---|
| javax.servlet | >=1.42 |
| jakarta.servlet | >=1.42.9 |
