feat(core): Add OTLP gRPC protocol support for OpenTelemetry tracing (#37491)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: ocdejong

packages/@n8n/api-types/src/dto/index.ts

@@ -431,7 +431,13 @@ export {
 	type ListWorkflowReviewActivityResponse,
 } from './workflow-reviews/workflow-review-activity.dto';
 
-export { UpdateOtelSettingsDto } from './otel/update-otel-settings.dto';
+export {
+	UpdateOtelSettingsDto,
+	OTLP_PROTOCOLS,
+	otlpProtocolSchema,
+	exporterEndpointSchema,
+	type OtlpProtocol,
+} from './otel/update-otel-settings.dto';
 export { TestOtelTraceDto } from './otel/test-otel-trace.dto';
 
 export { InstanceAiExamplesQueryDto } from './instance-ai-examples/instance-ai-examples-query.dto';

packages/@n8n/api-types/src/dto/otel/__tests__/update-otel-settings.dto.test.ts

@@ -3,6 +3,7 @@ import { UpdateOtelSettingsDto } from '../update-otel-settings.dto';
 
 const validSettings = {
 	enabled: true,
+	exporterProtocol: 'http/protobuf',
 	exporterEndpoint: 'http://localhost:4318',
 	exporterTracingPath: '/v1/traces',
 	exporterServiceName: 'n8n',
@@ -14,17 +15,29 @@ const validSettings = {
 	productionExecutionsOnly: true,
 };
 
+const defaultedFields = ['exporterProtocol'];
+
 describe('UpdateOtelSettingsDto', () => {
-	it('requires every field (stays strict, so a partial body is rejected)', () => {
+	it('requires every field except the defaulted ones (so a partial body is rejected)', () => {
 		const result = UpdateOtelSettingsDto.safeParse({});
 
 		assert(!result.success, 'Expected validation to fail for an empty body');
 
-		// An empty body must report every field as missing. A field that carries a
-		// default would parse successfully instead of erroring — this guards the
-		// public API PUT against silently resetting omitted fields.
 		const missing = [...new Set(result.error.issues.map((issue) => String(issue.path[0])))].sort();
-		expect(missing).toEqual(Object.keys(validSettings).sort());
+		expect(missing).toEqual(
+			Object.keys(validSettings)
+				.filter((key) => !defaultedFields.includes(key))
+				.sort(),
+		);
+	});
+
+	it('defaults the exporter protocol when omitted (body predates the field)', () => {
+		const { exporterProtocol: _omitted, ...withoutProtocol } = validSettings;
+
+		const result = UpdateOtelSettingsDto.safeParse(withoutProtocol);
+
+		assert(result.success, 'Expected a body without exporterProtocol to stay valid');
+		expect(result.data.exporterProtocol).toBe('http/protobuf');
 	});
 
 	it('accepts a full body', () => {
@@ -48,6 +61,70 @@ describe('UpdateOtelSettingsDto', () => {
 		);
 	});
 
+	it.each(['http/protobuf', 'grpc'])('accepts the %s exporter protocol', (exporterProtocol) => {
+		const result = UpdateOtelSettingsDto.safeParse({ ...validSettings, exporterProtocol });
+
+		assert(result.success, `Expected ${exporterProtocol} to be a valid exporter protocol`);
+		expect(result.data.exporterProtocol).toBe(exporterProtocol);
+	});
+
+	it.each(['http/json', 'HTTP/PROTOBUF', 'http', 'gRPC', ''])(
+		'rejects %p as an exporter protocol',
+		(exporterProtocol) => {
+			const result = UpdateOtelSettingsDto.safeParse({ ...validSettings, exporterProtocol });
+
+			assert(!result.success, `Expected ${exporterProtocol} to be an invalid exporter protocol`);
+			expect(result.error.issues).toContainEqual(
+				expect.objectContaining({
+					code: 'invalid_enum_value',
+					path: ['exporterProtocol'],
+				}),
+			);
+		},
+	);
+
+	it.each([
+		'http://localhost:4318',
+		'https://collector.example.com:4317',
+		'http://[::1]:4317',
+		'HTTP://localhost:4318',
+		'HttpS://collector.example.com:4317',
+	])('accepts %p as an exporter endpoint', (exporterEndpoint) => {
+		const result = UpdateOtelSettingsDto.safeParse({ ...validSettings, exporterEndpoint });
+
+		assert(result.success, `Expected ${exporterEndpoint} to be a valid exporter endpoint`);
+		expect(result.data.exporterEndpoint).toBe(exporterEndpoint);
+	});
+
+	it.each(['localhost:4318', 'grpc://host:4317', 'ftp://x'])(
+		'rejects %p as an exporter endpoint',
+		(exporterEndpoint) => {
+			const result = UpdateOtelSettingsDto.safeParse({ ...validSettings, exporterEndpoint });
+
+			assert(!result.success, `Expected ${exporterEndpoint} to be an invalid exporter endpoint`);
+			expect(result.error.issues).toContainEqual(
+				expect.objectContaining({ path: ['exporterEndpoint'] }),
+			);
+		},
+	);
+
+	it('explains why a non-http endpoint scheme is rejected', () => {
+		const result = UpdateOtelSettingsDto.safeParse({
+			...validSettings,
+			exporterEndpoint: 'grpc://host:4317',
+		});
+
+		assert(!result.success, 'Expected validation to fail for a grpc:// exporter endpoint');
+		expect(result.error.issues).toContainEqual(
+			expect.objectContaining({
+				code: 'invalid_string',
+				validation: 'regex',
+				path: ['exporterEndpoint'],
+				message: 'Endpoint must start with http:// or https://. The scheme selects TLS.',
+			}),
+		);
+	});
+
 	it('rejects a sample rate outside the 0..1 range', () => {
 		const result = UpdateOtelSettingsDto.safeParse({ ...validSettings, tracesSampleRate: 2 });
 
@@ -64,39 +141,76 @@ describe('UpdateOtelSettingsDto', () => {
 
 describe('TestOtelTraceDto', () => {
 	const validConnection = {
+		exporterProtocol: 'http/protobuf',
 		exporterEndpoint: 'http://localhost:4318',
 		exporterTracingPath: '/v1/traces',
 		exporterServiceName: 'n8n',
 		exporterHeaders: '',
 		startupConnectivityTimeoutMs: 2_000,
 	};
 
-	it('requires every connection field (stays strict)', () => {
+	it('requires every connection field except the defaulted ones (stays strict)', () => {
 		const result = TestOtelTraceDto.safeParse({});
 
 		assert(!result.success, 'Expected validation to fail for an empty body');
 
 		const missing = [...new Set(result.error.issues.map((issue) => String(issue.path[0])))].sort();
-		expect(missing).toEqual(Object.keys(validConnection).sort());
+		expect(missing).toEqual(
+			Object.keys(validConnection)
+				.filter((key) => !defaultedFields.includes(key))
+				.sort(),
+		);
 	});
 
-	it('accepts a full connection body', () => {
-		const result = TestOtelTraceDto.safeParse(validConnection);
-		expect(result.success).toBe(true);
+	it('accepts a gRPC connection body', () => {
+		const result = TestOtelTraceDto.safeParse({
+			...validConnection,
+			exporterProtocol: 'grpc',
+			exporterEndpoint: 'http://localhost:4317',
+		});
+
+		assert(result.success, 'Expected a gRPC connection body to be valid');
+		expect(result.data.exporterProtocol).toBe('grpc');
 	});
 
-	it('rejects an invalid exporter endpoint', () => {
+	it('rejects an unsupported exporter protocol', () => {
 		const result = TestOtelTraceDto.safeParse({
 			...validConnection,
-			exporterEndpoint: 'not-a-url',
+			exporterProtocol: 'http/json',
 		});
 
-		assert(!result.success, 'Expected validation to fail for an invalid exporter endpoint');
+		assert(!result.success, 'Expected validation to fail for an unsupported exporter protocol');
+		expect(result.error.issues).toContainEqual(
+			expect.objectContaining({
+				code: 'invalid_enum_value',
+				path: ['exporterProtocol'],
+			}),
+		);
+	});
+
+	it('accepts an https exporter endpoint', () => {
+		const result = TestOtelTraceDto.safeParse({
+			...validConnection,
+			exporterEndpoint: 'https://collector.example.com:4317',
+		});
+
+		assert(result.success, 'Expected an https exporter endpoint to be valid');
+		expect(result.data.exporterEndpoint).toBe('https://collector.example.com:4317');
+	});
+
+	it('rejects a non-http exporter endpoint scheme', () => {
+		const result = TestOtelTraceDto.safeParse({
+			...validConnection,
+			exporterEndpoint: 'grpc://host:4317',
+		});
+
+		assert(!result.success, 'Expected validation to fail for a grpc:// exporter endpoint');
 		expect(result.error.issues).toContainEqual(
 			expect.objectContaining({
 				code: 'invalid_string',
-				validation: 'url',
+				validation: 'regex',
 				path: ['exporterEndpoint'],
+				message: 'Endpoint must start with http:// or https://. The scheme selects TLS.',
 			}),
 		);
 	});

packages/@n8n/api-types/src/dto/otel/test-otel-trace.dto.ts

@@ -3,6 +3,7 @@ import { Z } from '../../zod-class';
 
 export class TestOtelTraceDto extends Z.class(
 	UpdateOtelSettingsDto.schema.pick({
+		exporterProtocol: true,
 		exporterEndpoint: true,
 		exporterTracingPath: true,
 		exporterServiceName: true,

packages/@n8n/api-types/src/dto/otel/update-otel-settings.dto.ts

@@ -2,9 +2,22 @@ import { z } from 'zod';
 
 import { Z } from '../../zod-class';
 
+export const OTLP_PROTOCOLS = ['http/protobuf', 'grpc'] as const;
+
+export type OtlpProtocol = (typeof OTLP_PROTOCOLS)[number];
+
+export const otlpProtocolSchema = z.enum(OTLP_PROTOCOLS);
+
+export const exporterEndpointSchema = z
+	.string()
+	.url()
+	.regex(/^https?:\/\//i, 'Endpoint must start with http:// or https://. The scheme selects TLS.');
+
 export class UpdateOtelSettingsDto extends Z.class({
 	enabled: z.boolean(),
-	exporterEndpoint: z.string().url(),
+	// Defaulted so a body from before this field existed still parses.
+	exporterProtocol: otlpProtocolSchema.default('http/protobuf'),
+	exporterEndpoint: exporterEndpointSchema,
 	exporterTracingPath: z.string(),
 	exporterServiceName: z.string().min(1),
 	exporterHeaders: z.string(),

packages/cli/package.json

@@ -140,6 +140,7 @@
     "@chat-adapter/telegram": "catalog:",
     "@daytona/sdk": "catalog:",
     "@google-cloud/secret-manager": "5.6.0",
+    "@grpc/grpc-js": "^1.14.3",
     "@joplin/turndown-plugin-gfm": "catalog:",
     "@langchain/core": "catalog:",
     "@modelcontextprotocol/node": "catalog:",
@@ -181,6 +182,7 @@
     "@n8n_io/license-sdk": "3.0.0",
     "@opentelemetry/api": "catalog:",
     "@opentelemetry/core": "2.10.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.221.0",
     "@opentelemetry/instrumentation": "^0.221.0",
     "@opentelemetry/resources": "^2.10.0",

packages/cli/src/modules/otel/README.md

@@ -135,3 +135,53 @@ Start n8n & point it at the jaeger instance
 cd packages/cli
 N8N_OTEL_ENABLED=true N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 pnpm run dev
 ```
+
+### Wire protocol (OTLP/HTTP vs OTLP/gRPC)
+
+`N8N_OTEL_EXPORTER_OTLP_PROTOCOL` selects how spans are delivered. It mirrors the
+upstream `OTEL_EXPORTER_OTLP_PROTOCOL` spec and accepts:
+
+| Value                     | Exporter                                   | Conventional port |
+| ------------------------- | ------------------------------------------ | ----------------- |
+| `http/protobuf` (default) | `@opentelemetry/exporter-trace-otlp-proto` | 4318              |
+| `grpc`                    | `@opentelemetry/exporter-trace-otlp-grpc`  | 4317              |
+
+```
+cd packages/cli
+N8N_OTEL_ENABLED=true \
+  N8N_OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
+  N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317 \
+  pnpm run dev
+```
+
+Notes:
+
+- Pick `grpc` only when the collector requires it (or for high span volume through
+  infrastructure that passes HTTP/2 through cleanly). `http/protobuf` traverses
+  proxies and firewalls more reliably and is easier to debug.
+- The endpoint scheme controls TLS for **both** protocols: `https://` uses TLS,
+  `http://` does not. There is no `grpc://` scheme.
+- Because the scheme is load-bearing, `N8N_OTEL_EXPORTER_OTLP_ENDPOINT` must be an
+  `http://` or `https://` URL. n8n logs a warning and uses the default endpoint if
+  the value has another scheme or no scheme, e.g. `localhost:4318`. The scheme is
+  matched case-insensitively, and n8n lowercases it before it reaches the exporter.
+- gRPC endpoints take **no URL path**, so `N8N_OTEL_EXPORTER_OTLP_TRACING_PATH` is
+  ignored when the protocol is `grpc`.
+- `N8N_OTEL_EXPORTER_OTLP_HEADERS` entries are sent as gRPC metadata. Keys are
+  lowercased (gRPC metadata keys are lowercase ASCII); an entry grpc-js rejects is
+  skipped with a warning instead of failing startup.
+- The startup connectivity check waits for a grpc-js channel to become ready for
+  `grpc` (an HTTP `HEAD` request is meaningless against an HTTP/2-only server).
+  The channel dials the host and port of the endpoint, so readiness proves TCP,
+  the TLS handshake for `https://`, and an HTTP/2 connection. It is not proof that
+  OTLP/gRPC is served there — use "Send test trace" in Settings → OpenTelemetry
+  for the real check.
+- An endpoint without a port dials the grpc-js default port 443, not 4317. Always
+  give the port, e.g. `http://127.0.0.1:4317`.
+- The check uses the default TLS trust store. It does not use the certificate
+  material that the exporter reads from `OTEL_EXPORTER_OTLP_CERTIFICATE`,
+  `OTEL_EXPORTER_OTLP_CLIENT_KEY` and `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, so a
+  collector behind a private CA, or one that needs mTLS, can fail the check and
+  still receive spans.
+- n8n has no setting for a custom CA or mTLS. Use the upstream
+  `OTEL_EXPORTER_OTLP_*` certificate variables above, or `NODE_EXTRA_CA_CERTS`.

packages/cli/src/modules/otel/__tests__/otel-lifecycle-handler.test.ts

@@ -43,6 +43,7 @@ function makeOtelSettingsService(
 		enabled: true,
 		productionExecutionsOnly: false,
 		includeNodeSpans: true,
+		exporterProtocol: 'http/protobuf',
 		exporterEndpoint: 'http://localhost:4318',
 		exporterTracingPath: '/v1/traces',
 		exporterServiceName: 'n8n',

packages/cli/src/modules/otel/__tests__/otel-settings.controller.test.ts

@@ -19,6 +19,7 @@ const res = mock<Response>();
 
 const baseSettings: OtelConfig = {
 	enabled: true,
+	exporterProtocol: 'http/protobuf',
 	exporterEndpoint: 'https://collector.example.com',
 	exporterTracingPath: '/v1/traces',
 	exporterHeaders: '',
@@ -131,6 +132,7 @@ describe('OtelSettingsController', () => {
 
 	describe('testTrace', () => {
 		const dto: OtelConnectionParams = {
+			exporterProtocol: 'http/protobuf',
 			exporterEndpoint: 'https://collector.example.com',
 			exporterTracingPath: '/v1/traces',
 			exporterServiceName: 'n8n-prod',