OTel Collector & Arrakis Endpoint

This is the canonical reference for the Arrakis OTLP ingest endpoint, authentication, optional mTLS, egress allowlist, and connectivity verification. Per-tool deployment pages link here instead of duplicating the same setup material.

Endpoint shape

Arrakis exposes an OTLP collector at a tenant-scoped hostname. Two protocols are supported: OTLP/gRPC and OTLP/HTTP (protobuf or JSON).

Protocol	Default port	Endpoint placeholder
OTLP/gRPC	4317	`https://otlp.<tenant>.arrakis.security:4317`
OTLP/HTTP (protobuf)	4318	`https://otlp.<tenant>.arrakis.security:4318`
OTLP/HTTP (JSON)	4318	`https://otlp.<tenant>.arrakis.security:4318`

These are placeholders. The real per-tenant hostname is provisioned in the Arrakis platform under Settings → Integrations → Deployment.

Authentication

Bearer token via the standard OTel header environment variable:


OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <tenant-token>"

For OTLP/gRPC the static header value is sent as-is. For OTLP/HTTP (protobuf or JSON), Claude Code additionally supports a dynamic headers helper script via the otelHeadersHelper setting — useful when Bearer tokens are minted from a workload-identity provider that rotates faster than the 29-minute default refresh. Cross-reference: see the Claude Code page for otelHeadersHelper setup.

mTLS (optional)

Protocol	Client cert env vars	Trust the collector CA with
`http/protobuf`, `http/json`	`CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY`, optional `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` (Claude Code only)	`NODE_EXTRA_CA_CERTS`
`grpc`	`OTEL_EXPORTER_OTLP_CLIENT_KEY`, `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` (or the per-signal variants)	`OTEL_EXPORTER_OTLP_CERTIFICATE`

The gRPC client variables are standard OpenTelemetry SDK names, so any OTel-instrumented tool can use them. The CLAUDE_CODE_CLIENT_* names are Claude Code specific.

Egress allowlist

Customer egress firewalls must allow outbound TCP from developer endpoints to the tenant ingest hostname on the chosen OTLP port — typically 443 for HTTPS-fronted gRPC/HTTP, or the explicit 4317/4318. The live IP/CIDR list for the tenant ingest is published in the Arrakis console; do not hard-code values.

Placeholder firewall rule:


ALLOW out TCP/443 from <developer-endpoint-subnet> to <tenant-ingest-host>

If your egress is identity-aware (Zscaler, Netskope, etc.), add <tenant-ingest-host> to the allowlist for the developer user group.

Verifying connectivity

Three concrete probes.

a) TCP/TLS handshake.


curl -v https://<tenant-ingest-host>:4318/v1/logs

Expected: TLS handshake succeeds, server returns 405 or 415 (POST-only endpoint).

b) Synthetic OTLP/HTTP log POST (proves auth header end-to-end).


curl -v -X POST \
  -H "Authorization: Bearer <tenant-token>" \
  -H "Content-Type: application/json" \
  --data '{"resourceLogs":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"arrakis-egress-test"}}]},"scopeLogs":[{"logRecords":[{"timeUnixNano":"0","severityText":"INFO","body":{"stringValue":"connectivity probe"}}]}]}]}' \
  https://<tenant-ingest-host>:4318/v1/logs

Expected: HTTP 200 or 202 with empty body.

c) Failure-mode mapping.

HTTP / network response	Likely cause
`Connection refused` / timeout	Egress firewall not allowlisted
`SSL: CERTIFICATE_VERIFY_FAILED`	Corporate TLS-inspection proxy intercepting; add Arrakis CA bundle to `NODE_EXTRA_CA_CERTS` or bypass inspection for the ingest host
`401 Unauthorized`	`Authorization` header missing or token wrong
`403 Forbidden`	Token valid but tenant scope mismatch — re-issue from Arrakis console
`404 Not Found`	Wrong path; ensure `/v1/logs`, `/v1/metrics`, or `/v1/traces`

Where to get tenant-specific values

Sign in to the Arrakis platform → Settings → Integrations → Deployment. The tenant OTLP hostname, header secret, and egress allowlist are listed there. Copy them into your MDM payload directly — docs use placeholders so they stay generic.

Arrakis namespace convention

Every byte Arrakis writes to a customer endpoint follows a single namespacing convention. The goal is that offboarding can deterministically remove just our content without disturbing customer-owned configuration.

Owned absolute path prefix. Every binary, hook, wrapper, and drop-in fragment lives under a single Arrakis-owned absolute path on each OS. Identifying Arrakis-controlled bytes is then a path-prefix match — robust against hand edits.
Drop-in fragments over single-file overwrites. Where the host application supports a drop-in directory (for example Claude Code’s managed-settings.d/), Arrakis ships its policy as a sortable-prefixed fragment file. Customer base files are never overwritten.
Namespaced metadata field on shared JSON entries. Where Arrakis must add an entry to a customer-shared JSON file (for example Cursor’s hooks.json), every entry includes a namespaced metadata field carrying owner, id, and version. Removal scripts filter on the owner sub-field. The format constraints of the host file (e.g., strict JSON, no comments) are respected — no comment markers.
Match-by-OR on cleanup. Cleanup scripts match either the Arrakis path prefix in command OR the namespaced metadata field, so removal still works if a customer hand-edits one identifier away.
Always back up before in-place edits. Cleanup scripts copy the target file to <file>.bak.<timestamp> before any jq or PowerShell modification, so the customer can roll back in seconds.

Applied consistently, this convention means offboarding is a deterministic, scriptable, reversible operation rather than a careful hand-edit.

Concrete file names, paths, and field identifiers are provisioned per-tenant; see the Arrakis platform Settings → Integrations → Deployment page for the values applied to your fleet.