intergral
diff --git a/‎docs/Getting-started/Tutorials/otel-migration.md‎
Lines changed: 192 additions & 0 deletions b/‎docs/Getting-started/Tutorials/otel-migration.md‎
Lines changed: 192 additions & 0 deletions
diff --git a/‎docs/Getting-started/Tutorials/otel-shipping.md‎
Lines changed: 201 additions & 0 deletions b/‎docs/Getting-started/Tutorials/otel-shipping.md‎
Lines changed: 201 additions & 0 deletions
@@ -0,0 +1,192 @@
+# Migrating from a dual OTel + FR agent setup
+
+From version **2025.2.0**, the FusionReactor agent ships OTel data natively. If you were previously running a standalone OTel Java agent alongside the FR agent, you can remove it and let the FR agent handle shipping directly.
+
+This page covers what the FR agent handles, what it does not, and how to migrate your collector configuration.
+
+## What the FR agent handles
+
+The FR agent (2025.2.0+) automatically collects and ships:
+
+- **Traces** - all request traces instrumented by the FR agent
+- **Metrics** - JVM metrics, HTTP request metrics, and FR agent instrumentation metrics
+- **Logs** - application logs captured by the FR agent
+
+These are shipped via the built-in OTel exporter to whichever endpoint you configure (OpsPilot by default).
+
+## What the FR agent does not handle
+
+### Custom metrics via `GlobalOpenTelemetry`
+
+The FR agent does not register itself as the global OTel SDK instance. If your application code calls `GlobalOpenTelemetry.get()` to record custom metrics or spans, those calls will return a no-op implementation - your custom instrumentation will not be collected.
+
+If you rely on custom metrics or spans created via `GlobalOpenTelemetry`, you have two options:
+
+- **Keep a standalone OTel agent** for custom instrumentation alongside the FR agent (point both at the same collector)
+- **Initialise the OTel SDK explicitly** in your application code so it does not depend on the global instance
+
+Example of explicit SDK initialisation (Java):
+
+```java
+SdkMeterProvider meterProvider = SdkMeterProvider.builder()
+    .registerMetricReader(
+        PeriodicMetricReader.builder(
+            OtlpGrpcMetricExporter.builder()
+                .setEndpoint("http://localhost:4317")
+                .build()
+        ).build()
+    )
+    .build();
+
+OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
+    .setMeterProvider(meterProvider)
+    .build();
+
+Meter meter = openTelemetry.getMeter("your-instrumentation-name");
+```
+
+This creates an independent OTel instance that ships to the same collector as the FR agent, without depending on the global singleton.
+
+### FRAPI metrics
+
+Metrics recorded via the FusionReactor FRAPI are captured locally and visible in the FR UI. They are not currently included in OTel shipping.
+
+## Migration steps
+
+### Step 1: Remove the standalone OTel agent
+
+Remove the `-javaagent:/path/to/opentelemetry-javaagent.jar` JVM argument from your startup configuration. The FR agent now handles OTel shipping, so the standalone agent is no longer needed for standard instrumentation.
+
+If you have custom metrics via `GlobalOpenTelemetry`, see the section above before removing the standalone agent.
+
+### Step 2: Update your collector configuration
+
+If you were previously sending OTel data from a standalone agent to a collector, and that collector was already forwarding to OpsPilot, you need to update the metrics pipeline to use Prometheus Remote Write format. OpsPilot does not accept raw OTLP metrics.
+
+=== "OTel Collector (before)"
+
+    ```yaml
+    exporters:
+      otlp/opspilot:
+        endpoint: https://api.fusionreactor.io
+        headers:
+          authorization: "${env:FR_API_KEY}"
+
+    service:
+      pipelines:
+        metrics:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [otlp/opspilot]
+    ```
+
+=== "OTel Collector (after)"
+
+    ```yaml
+    exporters:
+      prometheusremotewrite/opspilot:
+        endpoint: https://api.fusionreactor.io/v1/metrics
+        headers:
+          authorization: "${env:FR_API_KEY}"
+
+      otlphttp/opspilot:
+        endpoint: https://api.fusionreactor.io
+        headers:
+          authorization: "${env:FR_API_KEY}"
+
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [otlphttp/opspilot]
+        metrics:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [prometheusremotewrite/opspilot]
+        logs:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [otlphttp/opspilot]
+    ```
+
+    !!! warning
+        Use the `otel/opentelemetry-collector-contrib` image. The standard `otel/opentelemetry-collector` image does not include the `prometheusremotewrite` exporter.
+
+=== "Alloy (before)"
+
+    ```hcl
+    otelcol.exporter.otlphttp "opspilot" {
+      client {
+        endpoint = "https://api.fusionreactor.io"
+        headers  = {
+          "authorization" = env("FR_API_KEY"),
+        }
+      }
+    }
+
+    otelcol.processor.batch "default" {
+      output {
+        metrics = [otelcol.exporter.otlphttp.opspilot.input]
+        logs    = [otelcol.exporter.otlphttp.opspilot.input]
+        traces  = [otelcol.exporter.otlphttp.opspilot.input]
+      }
+    }
+    ```
+
+=== "Alloy (after)"
+
+    ```hcl
+    // Traces and logs via OTLP HTTP
+    otelcol.exporter.otlphttp "opspilot" {
+      client {
+        endpoint = "https://api.fusionreactor.io"
+        headers  = {
+          "authorization" = env("FR_API_KEY"),
+        }
+      }
+    }
+
+    // Metrics via Prometheus Remote Write
+    otelcol.exporter.prometheus "opspilot" {
+      forward_to = [prometheus.remote_write.opspilot.receiver]
+    }
+
+    prometheus.remote_write "opspilot" {
+      endpoint {
+        url = "https://api.fusionreactor.io/v1/metrics"
+        headers = {
+          "authorization" = env("FR_API_KEY"),
+        }
+      }
+    }
+
+    otelcol.processor.batch "default" {
+      output {
+        metrics = [otelcol.exporter.prometheus.opspilot.input]
+        logs    = [otelcol.exporter.otlphttp.opspilot.input]
+        traces  = [otelcol.exporter.otlphttp.opspilot.input]
+      }
+    }
+    ```
+
+    !!! warning
+        OpsPilot requires the raw API key in the `Authorization` header without a `Bearer ` prefix. Do not use `otelcol.auth.bearer` - it adds the prefix automatically.
+
+### Step 3: Verify data is arriving
+
+1. Open the **Cloud Status** page in the local FusionReactor UI (`localhost:8088` by default) and confirm shipping is active.
+2. Check OpsPilot to verify metrics, traces, and logs are appearing.
+3. If you have custom instrumentation, confirm those metrics are still being recorded (either via the standalone agent you kept, or via the explicitly initialised SDK).
+
+## Summary
+
+| | Standalone OTel agent | FR agent 2025.2.0+ |
+|---|---|---|
+| Standard JVM metrics | Yes | Yes |
+| Request traces | Yes | Yes |
+| Logs | Yes | Yes |
+| Custom `GlobalOpenTelemetry` metrics | Yes | No |
+| FRAPI metrics | No | Local only |
+
+For the full shipping configuration reference, see [OTel shipping with FusionReactor](otel-shipping.md).
@@ -0,0 +1,201 @@
+# OTel shipping with FusionReactor
+
+From version **2025.2.0**, the FusionReactor agent includes built-in OpenTelemetry (OTel) support and ships metrics, traces, and logs directly to any OTel-compatible destination. You no longer need to run a separate OTel agent alongside FusionReactor.
+
+## Shipping modes
+
+There are three shipping modes depending on your setup:
+
+| Mode | When it applies | Config required |
+|---|---|---|
+| **Default (OpsPilot)** | No existing OTel endpoint configured | None |
+| **Single endpoint** | You configure one external OTel endpoint | Set `otel.exporter.otlp.endpoint` |
+| **Multiple destinations** | You need to ship to more than one destination | Collector required |
+
+## Default: shipping to OpsPilot
+
+Without any OTel endpoint configured, the FR agent automatically ships all metrics, traces, and logs to OpsPilot. No configuration is needed.
+
+If you upgrade from a pre-2025.2.0 agent with no existing OTel configuration, your data will appear in OpsPilot automatically.
+
+## Single endpoint shipping
+
+To override the OpsPilot default and ship to a single external provider (Datadog, New Relic, Dash0, Grafana, etc.), configure the endpoint via system property or environment variable:
+
+```properties
+otel.exporter.otlp.endpoint=https://your-endpoint:4317
+```
+
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-endpoint:4317
+```
+
+!!! warning
+    When you configure an external endpoint, shipping to OpsPilot stops. To keep sending data to OpsPilot alongside another destination, use a collector instead.
+
+If you had an existing OTel configuration before upgrading to 2025.2.0, the FR agent picks up your configured endpoint automatically - your data will go to that endpoint rather than OpsPilot.
+
+## Multiple destinations via a collector
+
+To ship to more than one destination simultaneously, point the FR agent at a local collector, then configure the collector to fan out to multiple destinations.
+
+The FR agent configuration is the same regardless of which collector you use:
+
+```properties
+otel.exporter.otlp.endpoint=http://localhost:4317
+```
+
+Then configure your collector:
+
+=== "OTel Collector"
+
+    The OpenTelemetry Collector uses YAML configuration. Create or edit your `collector.yaml`:
+
+    ```yaml
+    receivers:
+      otlp:
+        protocols:
+          grpc:
+            endpoint: 0.0.0.0:4317
+          http:
+            endpoint: 0.0.0.0:4318
+
+    processors:
+      batch:
+        timeout: 5s
+        send_batch_size: 1000
+
+    exporters:
+      otlp/grafana:
+        endpoint: https://<your-stack>.grafana.net/otlp
+        headers:
+          authorization: "Basic <base64(instanceID:apiToken)>"
+
+      prometheusremotewrite/opspilot:
+        endpoint: https://api.fusionreactor.io/v1/metrics
+        headers:
+          authorization: "${env:FR_API_KEY}"
+
+      otlphttp/opspilot:
+        endpoint: https://api.fusionreactor.io
+        headers:
+          authorization: "${env:FR_API_KEY}"
+
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [otlp/grafana, otlphttp/opspilot]
+        metrics:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [otlp/grafana, prometheusremotewrite/opspilot]
+        logs:
+          receivers: [otlp]
+          processors: [batch]
+          exporters: [otlp/grafana, otlphttp/opspilot]
+    ```
+
+    !!! info "OpsPilot metrics format"
+        OpsPilot ingests metrics in **Prometheus Remote Write format**, not raw OTLP. The metrics pipeline must use the `prometheusremotewrite` exporter targeting `https://api.fusionreactor.io/v1/metrics`. Use the `otel/opentelemetry-collector-contrib` image - the standard `otel/opentelemetry-collector` image does not include this exporter.
+
+=== "Alloy"
+
+    Grafana Alloy uses HCL syntax. Create or edit your `collector.alloy`:
+
+    ```hcl
+    otelcol.receiver.otlp "default" {
+      grpc {
+        endpoint = "0.0.0.0:4317"
+      }
+      http {
+        endpoint = "0.0.0.0:4318"
+      }
+
+      output {
+        metrics = [otelcol.processor.batch.default.input]
+        logs    = [otelcol.processor.batch.default.input]
+        traces  = [otelcol.processor.batch.default.input]
+      }
+    }
+
+    otelcol.processor.batch "default" {
+      timeout         = "5s"
+      send_batch_size = 1000
+
+      output {
+        metrics = [otelcol.exporter.otlp.grafana.input, otelcol.exporter.prometheus.opspilot.input]
+        logs    = [otelcol.exporter.otlp.grafana.input, otelcol.exporter.otlphttp.opspilot.input]
+        traces  = [otelcol.exporter.otlp.grafana.input, otelcol.exporter.otlphttp.opspilot.input]
+      }
+    }
+
+    otelcol.exporter.otlp "grafana" {
+      client {
+        endpoint = "https://<your-stack>.grafana.net/otlp"
+        auth     = otelcol.auth.basic.grafana.handler
+      }
+    }
+
+    otelcol.auth.basic "grafana" {
+      username = env("GRAFANA_INSTANCE_ID")
+      password = env("GRAFANA_API_TOKEN")
+    }
+
+    // OpsPilot traces and logs
+    otelcol.exporter.otlphttp "opspilot" {
+      client {
+        endpoint = "https://api.fusionreactor.io"
+        headers  = {
+          "authorization" = env("FR_API_KEY"),
+        }
+      }
+    }
+
+    // OpsPilot metrics - convert to Prometheus Remote Write format
+    otelcol.exporter.prometheus "opspilot" {
+      forward_to = [prometheus.remote_write.opspilot.receiver]
+    }
+
+    prometheus.remote_write "opspilot" {
+      endpoint {
+        url = "https://api.fusionreactor.io/v1/metrics"
+        headers = {
+          "authorization" = env("FR_API_KEY"),
+        }
+      }
+    }
+    ```
+
+    !!! warning
+        OpsPilot requires the raw API key in the `Authorization` header **without** a `Bearer ` prefix. Use a plain `headers` map rather than `otelcol.auth.bearer`, which adds the prefix automatically.
+
+`FR_API_KEY` is your OpsPilot API key from **Account Settings > API Keys** in the OpsPilot UI. This is different from your FR licence key.
+
+## Troubleshooting
+
+### Verifying your configuration
+
+Check the **Cloud Status** page in the local FusionReactor UI (`localhost:8088` by default) to confirm that OTel shipping settings have been applied and shipping is active. Also review the agent startup logs for any configuration errors or warnings.
+
+### Data not appearing in OpsPilot
+
+- Verify your endpoint URL is correct
+- Check that authentication credentials are set via environment variables
+- Ensure the protocol matches the endpoint (gRPC uses port `4317`, HTTP uses `4318`)
+- Check collector logs if using a collector
+
+### Connection errors
+
+- Verify network connectivity to the endpoint
+- Check that firewall rules allow outbound connections on the required ports
+- Ensure the endpoint supports the protocol you have configured
+
+### Authentication failures
+
+- Verify that API keys/tokens are valid and not expired
+- Check the header format matches the provider's requirements
+- Ensure environment variables are set and accessible to the process
+
+For further help, see the [OpsPilot OpenTelemetry troubleshooting guide](https://docs.opspilot.com/Monitor-your-data/OpenTelemetry/Troubleshooting) or contact support via the chat bubble on this page.