n8n은 워크플로 및 노드 실행에 대한 OpenTelemetry{:target="_blank" .external-link} 트레이스를 내보낼 수 있습니다. 이 트레이스를 사용하여 실행 지연 시간을 모니터링하고, 장애를 디버그하며, 옵저버빌리티 스택 내 서비스 간 요청을 추적할 수 있습니다.

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 헤더{:target="_blank" .external-link}가 포함되어 있으면, n8n은 이를 워크플로 스팬의 부모로 사용합니다. 이를 통해 n8n 워크플로 트레이스를 업스트림 호출자와 연결합니다.
• 아웃바운드: HTTP Request node(및 n8n HTTP 헬퍼를 사용하는 다른 노드들)는 아웃바운드 요청에 traceparent 헤더를 주입할 수 있습니다. W3C 트레이스 컨텍스트를 지원하는 다운스트림 서비스는 트레이스를 이어받을 수 있습니다.
• 서브 워크플로: 서브 워크플로의 스팬은 상위 워크플로의 스팬을 부모로 사용합니다.
• 재개된 워크플로: 대기 후 워크플로가 재개될 때, 새 스팬은 스팬 링크를 사용하여 이전 스팬과 연결됩니다.

트레이싱 활성화#

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

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"

// 보안 강화를 위해 — 토큰을 입력할 경우 `_FILE` 접미사를 사용하는 것을 권장합니다:
export N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE=/mnt/otel-headers

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

샘플링#

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

# 트레이스의 10%만 내보내기
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 }}와 같은 표현식이 될 수 있습니다.

노드 속성 값은 문자열, 숫자, 또는 부울(boolean)로 결정되어야 합니다.

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

커스텀 노드를 빌드하는 경우, 코드에서 커스텀 키-값 쌍을 연결할 수 있습니다. 노드의 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.을 붙입니다. 값은 문자열, 숫자, 또는 부울(boolean)이어야 합니다.

이 API는 Code node에서는 사용할 수 없습니다. 도메인별 데이터로 스팬을 풍부하게 만들려는 노드 개발자를 위한 것입니다.

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

Jaeger로 테스트해보기#

로컬 Jaeger{:target="_blank" .external-link} 인스턴스로 트레이스를 전송하여 실제로 확인할 수 있습니다.

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. 트레이싱을 활성화하고 Jaeger를 가리키도록 n8n을 시작하세요. 설정 세부 사항은 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가 컬렉터의 기본 URL을 가리키는지 (/v1/traces 경로 제외).
• 컬렉터가 n8n 컨테이너 또는 호스트에서 접근 가능한지.
• 필요한 N8N_OTEL_EXPORTER_OTLP_HEADERS(예: 인증 토큰)가 설정되어 있는지.

n8n은 기본적으로 OpenTelemetry 진단을 warn 레벨로 기록합니다. 더 자세한 내용을 보려면 N8N_LOG_LEVEL=debug로 설정하세요.

커스텀 스팬 속성이 없는 경우#

다음을 확인하세요:

• Enterprise 라이선스가 있는지.
• N8N_OTEL_ENABLED가 true로 설정되어 있는지.
• 노드 수준 스팬 속성의 경우, N8N_OTEL_TRACES_INCLUDE_NODE_SPANS가 false로 설정되지 않았는지.

워커 트레이스에 상위 컨텍스트가 없는 경우#

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

관련 리소스#

• OpenTelemetry 환경 변수
• W3C 트레이스 컨텍스트 명세{:target="_blank" .external-link}
• OpenTelemetry 컬렉터 문서{:target="_blank" .external-link}
• n8n 로깅
• 모니터링