n8n은 워크플로 및 노드 실행에 대해 OpenTelemetry 트레이스를 내보낼 수 있습니다. 이 트레이스를 사용하여 실행 지연 시간을 모니터링하고, 실패를 디버깅하고, 관찰 가능성(observability) 스택 전반에서 서비스 간 요청을 추적할 수 있습니다.

n8n에서 OpenTelemetry 트레이싱에 대한 개요 영상을 시청해 보세요.

얻을 수 있는 것#

트레이싱을 켜면, n8n은 각 실행마다 두 종류의 스팬을 내보냅니다.

• workflow.execute: 워크플로 실행당 하나의 스팬입니다. 워크플로 ID, 이름, 버전, 노드 수, 실행 모드, 상태, 오류 유형(있는 경우)을 기록합니다.
• node.execute: 노드 실행당 하나의 스팬으로, 해당 워크플로 스팬 안에 중첩됩니다. 노드 ID, 이름, 유형, 버전, 입력 및 출력 아이템 수를 기록합니다.

각 스팬에는 n8n 인스턴스를 식별하는 리소스 속성이 포함됩니다.

• service.name (기본값 n8n)
• service.version (n8n 버전)
• n8n.instance.id
• n8n.instance.role (예: main, worker, webhook)

n8n은 트레이스 컨텍스트 전파도 처리합니다.

• 인바운드: 웹훅 요청에 W3C traceparent 헤더가 포함되어 있으면, n8n은 이를 워크플로 스팬의 부모로 사용합니다. 이렇게 하면 n8n 워크플로 트레이스가 상위 호출자와 연결됩니다.
• 아웃바운드: HTTP Request node(및 n8n HTTP 헬퍼를 사용하는 다른 노드)는 아웃바운드 요청에 traceparent 헤더를 주입할 수 있습니다. 따라서 W3C 트레이스 컨텍스트를 지원하는 다운스트림 서비스는 트레이스를 이어갈 수 있습니다.
• 서브 워크플로: 서브 워크플로의 스팬은 상위 워크플로의 스팬을 부모로 사용합니다.
• 재개된 워크플로: 대기 후 워크플로가 재개되면, 새 스팬은 스팬 링크를 사용하여 이전 스팬으로 다시 연결됩니다.

UI에서 트레이싱 활성화#

환경 변수를 설정하는 대신, Settings > OpenTelemetry에서 트레이싱을 구성할 수 있습니다. n8n은 재시작 없이 변경 사항을 적용하며, 큐 모드에서 워커와 웹훅 프로세서 전반에 걸쳐 이를 다시 로드합니다.

트레이싱을 구성하려면 다음을 수행하세요.

1. Settings > OpenTelemetry를 선택합니다.
2. Enable OpenTelemetry를 켭니다.
3. Collector connection 아래에서 OTLP endpoint와 기타 연결 세부 정보를 입력합니다.
4. Tracing 아래에서 샘플링 및 스팬 옵션을 설정합니다.
5. Save settings를 선택합니다.

n8n이 컬렉터에 연결할 수 있는지 확인하려면, Verify configuration 아래에서 Send test trace를 선택하세요. n8n은 테스트 스팬 하나를 전송하고 컬렉터가 이를 수락했는지 보고합니다. 설정을 저장하기 전이나 후 어느 시점에도 실행할 수 있습니다.

각 필드는 환경 변수에 매핑되며, 이는 필드의 툴팁에 표시됩니다. 전체 목록은 OpenTelemetry 환경 변수를 참고하세요.

환경 변수로 트레이싱 활성화#

워크플로 트레이싱을 활성화하려는 각 n8n 인스턴스(main, 워커, 웹훅 프로세서)에 다음 환경 변수를 설정하세요.

export N8N_OTEL_ENABLED=true
export N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<your-collector-host>:4318

n8n을 재시작하세요. 인스턴스는 Protobuf 인코딩을 사용하여 OTLP HTTP를 통해 스팬을 내보내기 시작합니다.

n8n은 기본적으로 엔드포인트에 /v1/traces를 추가합니다. N8N_OTEL_EXPORTER_OTLP_ENDPOINT는 트레이스 경로가 아니라 컬렉터의 기본 URL을 가리켜야 합니다.

컬렉터에 인증이 필요한 경우, N8N_OTEL_EXPORTER_OTLP_HEADERS를 key=value 쌍의 쉼표 구분 목록으로 설정하세요.

export N8N_OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your-token>,x-tenant=acme"

// For added protection - It is recommended to use the `_FILE` postfix if you are putting a token in here:
export N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE=/mnt/otel-headers

지원되는 변수의 전체 목록은 OpenTelemetry 환경 변수를 참고하세요.

샘플링#

기본적으로 n8n은 모든 트레이스를 내보냅니다. 트래픽이 많은 인스턴스에서 볼륨을 줄이려면, N8N_OTEL_TRACES_SAMPLE_RATE를 0에서 1 사이의 값으로 설정하세요.

# Export 10% of traces
export N8N_OTEL_TRACES_SAMPLE_RATE=0.1

n8n은 트레이스 ID 비율 샘플러를 사용하므로, 동일한 트레이스 ID는 해당 트레이스의 모든 스팬에 걸쳐 전부 샘플링되거나 전부 삭제됩니다.

스팬 볼륨 줄이기#

워크플로의 각 노드는 자체 스팬을 생성합니다. 노드가 많은 워크플로의 경우, 필요한 것보다 더 많은 데이터가 생성될 수 있습니다. 워크플로 수준 스팬만 내보내려면 다음을 설정하세요.

export N8N_OTEL_TRACES_INCLUDE_NODE_SPANS=false

n8n이 아웃바운드 HTTP 요청에 traceparent 헤더를 주입하지 않도록 하려면 다음을 설정하세요.

export N8N_OTEL_TRACES_INJECT_OUTBOUND=false

커스텀 스팬 속성#

프로젝트, 워크플로, 노드 스팬에 커스텀 속성을 추가할 수 있습니다. n8n은 각 커스텀 속성을 구성된 관찰 가능성 백엔드로 OpenTelemetry 스팬 속성으로 내보냅니다.

속성 값에 시크릿, 개인 데이터, 기타 민감한 값을 포함하지 마세요.

n8n은 다음과 같은 커스텀 속성 수준을 지원합니다.

프로젝트 및 워크플로 커스텀 스팬 속성은 n8n 2.24.0부터 제공됩니다. 노드 커스텀 스팬 속성은 n8n 2.22.0부터 제공됩니다.

프로젝트 스팬 속성 추가#

프로젝트 수준 스팬 속성을 추가하려면 다음을 수행하세요.

1. 프로젝트를 엽니다.
2. Project settings를 선택합니다.
3. Custom Span Attributes 아래에서 스팬 속성을 하나 이상 추가합니다.
4. Save를 선택합니다.

프로젝트 속성 값에는 일반 텍스트를 사용하세요.

워크플로 스팬 속성 추가#

워크플로 수준 스팬 속성을 추가하려면 다음을 수행하세요.

1. 워크플로를 엽니다.
2. Workflow settings를 엽니다.
3. Custom Span Attributes 아래에서 Configure를 선택합니다.
4. 스팬 속성을 하나 이상 추가합니다.
5. Save를 선택합니다.

워크플로 속성 값에는 일반 텍스트를 사용하세요.

노드 스팬 속성 추가#

노드 수준 스팬 속성을 추가하려면 다음을 수행하세요.

1. 노드를 열고 Settings 탭을 선택합니다.
2. Custom Span Attributes 아래에서 Add Attribute를 선택합니다.
3. Key를 입력합니다. 키는 일반 텍스트여야 합니다.
4. Value를 입력합니다. 값은 일반 텍스트이거나 ={{ $json.environment }}와 같은 표현식일 수 있습니다.

노드 속성 값은 문자열, 숫자, 불리언 중 하나로 해석되어야 합니다.

커스텀 노드에서 프로그래밍 방식으로 속성 추가#

커스텀 노드를 빌드하는 경우, 코드에서 커스텀 키-값 쌍을 첨부할 수 있습니다. 노드의 execute 메서드에서 setMetadata를 호출하세요.

async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
	this.setMetadata({
		tracing: {
			'llm.model': 'gpt-4o',
			'llm.token.input': 1500,
			'llm.token.output': 340,
		},
	});

	return [this.getInputData()];
}

n8n은 내보내지는 스팬에서 각 키 앞에 n8n.node.custom.을 붙입니다. 값은 문자열, 숫자, 불리언이어야 합니다.

이 API는 Code node에서는 사용할 수 없습니다. 스팬을 도메인 특화 데이터로 보강하고자 하는 노드 개발자를 위한 것입니다.

노드가 여기서 설정한 속성 키가 커스텀 노드 스팬 속성으로도 구성되어 있는 경우, 프로그래밍 방식으로 설정한 값이 우선합니다.

Jaeger로 사용해 보기#

로컬 Jaeger 인스턴스로 트레이스를 전송하여 실제 동작을 확인할 수 있습니다.

1. 다음 내용을 docker-compose.yml로 저장하세요.

services:
  jaeger:
    image: jaegertracing/jaeger:latest
    ports:
      - "16686:16686" # UI
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP

2. Jaeger를 시작하세요.

docker compose up -d

3. 트레이싱을 켠 상태로 n8n을 시작하고 Jaeger를 가리키도록 설정하세요. 설정 세부 정보는 n8n 시작하기를 참고하세요.

N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 n8n start

5. 워크플로를 실행한 다음, http://localhost:16686에서 Jaeger UI를 열고 서비스로 "n8n"을 선택한 후 "Find traces"를 클릭하여 n8n이 내보낸 OpenTelemetry 트레이스를 확인하세요.

스팬 속성#

워크플로 및 노드 스팬에는 다음과 같은 n8n 관련 속성이 포함됩니다.

워크플로 스팬 (workflow.execute)#

노드 스팬 (node.execute)#

노드가 실패하면, n8n은 표준 OpenTelemetry 예외 속성(exception.type, exception.message, exception.stacktrace)과 함께 스팬에 exception 이벤트를 기록합니다.

문제 해결#

백엔드에 트레이스가 나타나지 않음#

n8n이 시작 시 OTLP 엔드포인트에 연결할 수 없으면, 다음과 같은 오류를 기록합니다.

Failed to connect to OpenTelemetry OTLP endpoint during startup

다음을 확인하세요.

• N8N_OTEL_ENABLED이 true로 설정되어 있는지 확인합니다.
• N8N_OTEL_EXPORTER_OTLP_ENDPOINT가 (/v1/traces 경로가 아니라) 컬렉터의 기본 URL을 가리키는지 확인합니다.
• 컬렉터가 n8n 컨테이너 또는 호스트에서 도달 가능한지 확인합니다.
• 필요한 N8N_OTEL_EXPORTER_OTLP_HEADERS(예: 인증 토큰)가 설정되어 있는지 확인합니다.

n8n은 기본적으로 warn 수준에서 OpenTelemetry 진단 정보를 기록합니다. 더 자세한 정보를 보려면 N8N_LOG_LEVEL=debug를 설정하세요.

커스텀 스팬 속성이 누락됨#

다음을 확인하세요.

• Enterprise 라이선스를 보유하고 있는지 확인합니다.
• N8N_OTEL_ENABLED을 true로 설정했는지 확인합니다.
• 노드 수준 스팬 속성의 경우, N8N_OTEL_TRACES_INCLUDE_NODE_SPANS가 false로 설정되어 있지 않은지 확인합니다.

워커 트레이스에 부모 컨텍스트가 없음#

큐 모드에서 워커는 데이터베이스에서 부모 트레이스 컨텍스트를 읽습니다. main 인스턴스에만 OpenTelemetry 환경 변수를 설정한 경우, 워커 스팬은 부모 워크플로 트레이스에 연결되지 않습니다. 모든 인스턴스 유형에 동일한 변수를 설정하세요.

관련 리소스#

• OpenTelemetry 환경 변수
• W3C Trace Context 사양
• OpenTelemetry Collector 문서
• n8n 로깅
• 모니터링