diff --git a/src/content/docs/docs/azure-integration/azure-application-gateway-log-monitoring.mdx b/src/content/docs/docs/azure-integration/azure-application-gateway-log-monitoring.mdx index 9238b699..4de22094 100644 --- a/src/content/docs/docs/azure-integration/azure-application-gateway-log-monitoring.mdx +++ b/src/content/docs/docs/azure-integration/azure-application-gateway-log-monitoring.mdx @@ -147,7 +147,7 @@ exporters: debug: verbosity: detailed otlphttp: - endpoint: 'https://otel.kloudmate.dev:4318' + endpoint: 'https://otel.kloudmate.com:4318' headers: Authorization: # Your KloudMate API key diff --git a/src/content/docs/docs/profiling/index.mdx b/src/content/docs/docs/profiling/index.mdx index 86555c9d..a8065fcc 100644 --- a/src/content/docs/docs/profiling/index.mdx +++ b/src/content/docs/docs/profiling/index.mdx @@ -33,7 +33,7 @@ KloudMate accepts profiling data in either Opentelemetry Profiles signal format You need two things before you touch any application code: 1. **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -2. **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. See [API Keys](../platform/settings/api-keys/) if you need the full walkthrough. +2. **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. See [API Keys](../platform/settings/api-keys/) if you need the full walkthrough. ### Authenticate with Basic auth diff --git a/src/content/docs/docs/rum/correlate-rum-traces-with-opentelemetry-backends.mdx b/src/content/docs/docs/rum/correlate-rum-traces-with-opentelemetry-backends.mdx index 9eec0963..3a0fcc35 100644 --- a/src/content/docs/docs/rum/correlate-rum-traces-with-opentelemetry-backends.mdx +++ b/src/content/docs/docs/rum/correlate-rum-traces-with-opentelemetry-backends.mdx @@ -9,38 +9,75 @@ KloudMate's RUM lets you connect requests from your web apps to their related ba The RUM SDK by default adds [context propagation headers (W3C)](https://opentelemetry.io/docs/concepts/context-propagation/#propagation) to fetch and XHR requests made to the same origin. ::: -If you want to propagate these headers to a different origin, it can be configured at initialization. +To reach a backend on a different origin, configure the SDK to send the headers, then allow those headers in your backend's CORS policy. Do the first without the second and the browser blocks every call to that origin. -For example, if you want to propagate trace context headers to `https://api.example.com`, the RUM SDK would be initialized as shown below: +## Send the trace headers from the browser + +Pass the origins you want to propagate to as `propagateTraceHeaderCorsUrls`. To propagate trace context headers to `https://api.example.com`, initialize the SDK like this: ```javascript KloudMateRum.init({ - endpoint: 'https://otel.kloudmate.dev:4318', + endpoint: 'https://otel.kloudmate.com:4318', rumAccessToken: '', applicationName: 'my-app', version: '1', deploymentEnvironment: 'prod', sessionRecorder: { enabled: true, - } + }, instrumentations: { fetch: { - propagateTraceHeaderCorsUrls: [new RegExp('https://api.example.com.*')] + propagateTraceHeaderCorsUrls: [new RegExp('https://api\\.example\\.com.*')] }, xhr: { - propagateTraceHeaderCorsUrls: [new RegExp('https://api.example.com.*')] + propagateTraceHeaderCorsUrls: [new RegExp('https://api\\.example\\.com.*')] } } }); - ``` -This will add context propagation headers to backend requests. The backend can then generate its spans using this context. +This adds context propagation headers to backend requests. The backend can then generate its spans using this context. :::note You can find examples of context extraction on the backend here: [https://opentelemetry.io/docs/languages/js/propagation/#generic-example](https://opentelemetry.io/docs/languages/js/propagation/#generic-example) ::: +## Allow the trace headers in your backend's CORS policy + +:::caution +Skipping this step breaks the requests themselves, not just the tracing. +::: + +`traceparent` isn't a [CORS-safelisted request header](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_request_header), so adding it turns every cross-origin call into a preflighted one. Your backend has to name it in the `Access-Control-Allow-Headers` response header. If it doesn't, the browser blocks the request before it's ever sent: + +```text +Access to fetch at 'https://api.example.com/orders' from origin 'https://app.example.com' +has been blocked by CORS policy: Request header field traceparent is not allowed by +Access-Control-Allow-Headers in preflight response. +``` + +Add `traceparent` to the allowed headers, along with `tracestate` and `baggage` if your setup propagates them. With Express and the `cors` middleware: + +```javascript +app.use(cors({ + origin: 'https://app.example.com', + allowedHeaders: ['content-type', 'traceparent', 'tracestate', 'baggage'] +})); +``` + +Other stacks set the same header under a different name: `CORS_ALLOW_HEADERS` in django-cors-headers, `allowed_headers` in rack-cors, `Access-Control-Allow-Headers` in an nginx `add_header` directive. + +## Troubleshoot a broken correlation + +Match what you're seeing in the browser to the fix: + +| Symptom | Cause | Fix | +| --- | --- | --- | +| Requests succeed, but the browser session and the backend show separate traces | The SDK never attached `traceparent`, so the backend started its own trace | Add the origin to `propagateTraceHeaderCorsUrls` | +| Requests fail with `Request header field traceparent is not allowed by Access-Control-Allow-Headers` | The SDK attached `traceparent`, but the backend's preflight response rejects it | Add `traceparent` to `Access-Control-Allow-Headers` | + +To confirm the header is arriving, log `req.headers.traceparent` on the backend. A value means the trace is stitched: the ID it carries is the same one on the browser span. + **Sample Integration:** 1. Once the RUM and backend are integrated you can view the corresponding backend trace of a frontend request diff --git a/src/content/docs/guides/llm/instrument-python-app-with-openllmetry.mdx b/src/content/docs/guides/llm/instrument-python-app-with-openllmetry.mdx index a72cad6c..9930df93 100644 --- a/src/content/docs/guides/llm/instrument-python-app-with-openllmetry.mdx +++ b/src/content/docs/guides/llm/instrument-python-app-with-openllmetry.mdx @@ -15,7 +15,7 @@ OpenLLMetry does the instrumentation. It's an OpenTelemetry-native SDK from Trac - Python 3.9 or later. - An OpenAI API key ([where to find it](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key)). -- A KloudMate workspace API key, from **Settings → API Keys**. +- A KloudMate workspace API key, from **Settings → Ingest Keys**. ## Step 1: Set up the project diff --git a/src/content/docs/guides/profiling/dotnet.mdx b/src/content/docs/guides/profiling/dotnet.mdx index 0921e9f8..51818dbc 100644 --- a/src/content/docs/guides/profiling/dotnet.mdx +++ b/src/content/docs/guides/profiling/dotnet.mdx @@ -10,7 +10,7 @@ The [Pyroscope .NET profiler](https://github.com/grafana/pyroscope-dotnet) attac ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install diff --git a/src/content/docs/guides/profiling/ebpf.mdx b/src/content/docs/guides/profiling/ebpf.mdx index d099736a..d6454975 100644 --- a/src/content/docs/guides/profiling/ebpf.mdx +++ b/src/content/docs/guides/profiling/ebpf.mdx @@ -11,7 +11,7 @@ The [OpenTelemetry eBPF profiler](https://github.com/open-telemetry/opentelemetr - A Linux host with a kernel new enough for eBPF (4.19+; 5.x recommended) and privileged access to load BPF programs (`CAP_SYS_ADMIN`/`CAP_BPF`, typically run as root or in a privileged container). - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install and run @@ -21,7 +21,7 @@ The project ships a container image, so the fastest path is running it directly docker run --privileged --pid=host \ -v /sys/kernel/debug:/sys/kernel/debug:ro \ otel/opentelemetry-ebpf-profiler:latest \ - -collection-agent=https://otel.kloudmate.dev/v1/profiles/pyroscope \ + -collection-agent=https://otel.kloudmate.com/v1/profiles/pyroscope \ -secret-token=YOUR_API_KEY \ -environment=my-environment ``` diff --git a/src/content/docs/guides/profiling/go.mdx b/src/content/docs/guides/profiling/go.mdx index 5886a9dc..55a128f3 100644 --- a/src/content/docs/guides/profiling/go.mdx +++ b/src/content/docs/guides/profiling/go.mdx @@ -10,7 +10,7 @@ sidebar: ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install diff --git a/src/content/docs/guides/profiling/java.mdx b/src/content/docs/guides/profiling/java.mdx index b196b141..fcef1517 100644 --- a/src/content/docs/guides/profiling/java.mdx +++ b/src/content/docs/guides/profiling/java.mdx @@ -10,7 +10,7 @@ The Pyroscope Java integration runs as a [Java agent](https://github.com/grafana ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install diff --git a/src/content/docs/guides/profiling/nodejs.mdx b/src/content/docs/guides/profiling/nodejs.mdx index 82d4e642..2053288f 100644 --- a/src/content/docs/guides/profiling/nodejs.mdx +++ b/src/content/docs/guides/profiling/nodejs.mdx @@ -10,7 +10,7 @@ sidebar: ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install diff --git a/src/content/docs/guides/profiling/python.mdx b/src/content/docs/guides/profiling/python.mdx index 9987f815..0e6069eb 100644 --- a/src/content/docs/guides/profiling/python.mdx +++ b/src/content/docs/guides/profiling/python.mdx @@ -10,7 +10,7 @@ sidebar: ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install diff --git a/src/content/docs/guides/profiling/ruby.mdx b/src/content/docs/guides/profiling/ruby.mdx index cf83096b..d98e14de 100644 --- a/src/content/docs/guides/profiling/ruby.mdx +++ b/src/content/docs/guides/profiling/ruby.mdx @@ -10,7 +10,7 @@ The [pyroscope](https://github.com/grafana/pyroscope-rb) gem is Grafana's offici ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install diff --git a/src/content/docs/guides/profiling/rust.mdx b/src/content/docs/guides/profiling/rust.mdx index 91bd0f98..d3f5494e 100644 --- a/src/content/docs/guides/profiling/rust.mdx +++ b/src/content/docs/guides/profiling/rust.mdx @@ -10,7 +10,7 @@ The [pyroscope](https://github.com/grafana/pyroscope-rs) crate is Grafana's offi ## Prerequisites - **The ingest endpoint**: `https://otel.kloudmate.com/v1/profiles/pyroscope` -- **An API key** — go to **Settings → API Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. +- **An API key** — go to **Settings → Ingest Keys**, click **Add New**, and create an **Ingest Key – Backend**. Copy it immediately; KloudMate shows it only once. ## Install