Connect Grepr to observability vendors for standardized telemetry data collection and forwarding using the OpenTelemetry Protocol over HTTP, or OTLP/HTTP. # Configure connections to OpenTelemetry-compatible platforms The Grepr OpenTelemetry integration enables you to ingest telemetry data into Grepr from a collector that supports the OpenTelemetry Protocol over HTTP, or OTLP/HTTP, process the data with a Grepr pipeline, and then send the processed data to any observability vendor that accepts OTLP/HTTP requests. The OpenTelemetry integration supports logs and Application Performance Monitoring (APM) data, including traces and metrics. To send logs or APM data to a Grepr pipeline for processing, change your collector configuration to send them to a Grepr endpoint URL instead of your vendor's OTLP/HTTP endpoint. The Grepr OpenTelemetry integration works with any collector that supports OTLP/HTTP, including the OpenTelemetry Collector and Fluent Bit. The Grepr endpoint URL requires a Grepr-generated token for authentication. When you create an OpenTelemetry integration, Grepr automatically generates this token. In the UI, the token is displayed in a dialog after you create the integration. You must copy this token and include it in your collector configuration. When you use the REST API to create the integration, the token is returned in the response. You can use the Grepr UI or REST API to add an OpenTelemetry integration. To learn how to create an OpenTelemetry integration in the Grepr UI and configure collectors to send data to Grepr, see [_](#use-opentelemetry-integration). To learn how to configure OpenTelemetry-compatible vendor integrations, see [Use an OTLP/HTTP compatible vendor integration in a Grepr pipeline](#vendor-otel-configuration). To use the REST API, see the [OpenTelemetry Integration specification](/apis/api-spec#tag/OpenTelemetry-Integration). > Although this page describes using an integration to create a pipeline for sourcing and sending data with a single observability platform, your pipelines can use multiple integrations to source and sink data for different platforms. For example, you can create a pipeline with a Datadog integration that's used to source data from Datadog agents, and a Splunk integration and sink that sends the pipeline output to Splunk. ## Requirements Creating and configuring an OpenTelemetry integration requires the URL of the HTTP/HTTPS endpoint where your observability vendor accepts OpenTelemetry data. ## Use an OpenTelemetry integration in a Grepr pipeline \[#use-opentelemetry-integration] Use the following steps to create an OpenTelemetry integration in the Grepr UI and use the integration as a source and sink in a pipeline. ### Step 1: Create an OpenTelemetry integration \[#step1-create-integration] To create an OpenTelemetry integration in the Grepr UI: 1. Go to the **Integrations** page in the Grepr UI and click **Add new** next to **Observability Vendors**. 2. In the **Add Observability Vendor** dialog: * In the **Type** menu, select **Open Telemetry**. * In the **Name** field, enter a name for the integration. * In the **Endpoint** field, enter the URL for the HTTP/HTTPS endpoint. * Optional: To add any required headers, for example, authentication headers such as `Authorization: Bearer ` or `X-API-Key: `: * In the **HTTP Headers** section, click **Add Header** to open the **Add New Header** card. * To use a fixed value for the header, in the **Source** menu, select **Static Value** and enter the **Header Name** and **Header Value**. * To set the header value using an attribute from processed log events, in the **Source** menu, select **From Attribute**, enter the **Header Name** and **Attribute Path**. * To store the value securely and mask it in the UI, click the lock icon. Use this option for all sensitive values, such as API keys or tokens. * Click **Save**. 3. Click **Create**. 4. After clicking **Create**, the **Grepr Token** dialog appears with a Grepr-generated token. Click the **Copy to Clipboard** icon to copy the token. This token is required when you configure your collector to send data to Grepr. 5. Click **Confirm** to close the dialog. #### Optional: Grant team access to the integration When you have teams in your Grepr organization, you can grant access to the integration to one or more of those teams. To configure team access when you create or edit an integration: 1. In the **Grant Team Access** section, click the plus sign icon (+). 2. Select the team or teams that should be granted access to the integration. 3. Click **Create**. To learn more, see [Manage teams in the Grepr platform](/admin/manage-teams) and [Permissions in the Grepr platform](/grepr-platform/permissions). When you select **From Attribute** to set a header value, Grepr groups log events that share the same attribute value into the same outbound request, sets the header to that value, and forwards the events to your vendor's endpoint. Events with different values for the attribute are sent in separate requests with the corresponding header values. Use this option when downstream routing or tenancy depends on a per-log value, such as a Kubernetes namespace or a tenant identifier. If a log event does not have the configured attribute, or the attribute value fails Grepr's validation, for example, because it contains control characters or exceeds the maximum length, Grepr delivers the event but omits the header from the request. You can add both static and attribute-sourced headers to the same integration. Grepr merges them on each outbound request. ### Step 2: Add a source to your pipeline To add a source to your pipeline that uses the OpenTelemetry integration, select the integration when you create a pipeline. For an existing pipeline, go to the pipeline details page and in the left-hand navigation menu, click **Sources** and select the integration. ### Step 3: Configure forwarding to Grepr \[#configure-forwarding-to-grepr] To send data to Grepr, you configure your collector or agent to send it to the ingestion URL for your Grepr integration, rather than to your observability vendor's platform. To find the ingestion URL when using the Grepr UI to configure your pipeline, go to the details page for the pipeline, click **Sources** in the left pane, and copy the **Ingest URL**. If you connect to Grepr through AWS PrivateLink, copy the private ingestion URL and use it in place of the public ingestion URL. To learn more about sending data to Grepr over AWS PrivateLink, see [Securely forward observability data to Grepr with AWS PrivateLink](/admin/private-link). When you use the API, you can construct the ingestion URL using the following format: `https://-.ingest.grepr.ai/otlp` Replace `` with the identifier of the vendor integration used by your pipeline and replace `` with the identifier for your organization. To use the PrivateLink endpoint service, insert `.private` after the `ingest` host segment. Although all sources created from the same integration share the same ingestion URL, you can use a single integration to create sources for multiple pipelines. The Grepr platform ensures events are routed to the correct pipelines. Authenticate by sending the Grepr token in the `x-grepr-token` header. Replace `` in the examples below with the token generated when you created the OpenTelemetry integration in Step 1. Every sender in the tabs below can set a custom header. Some senders take the ingestion URL as it is and append the path for each signal themselves. Others need the full path for one signal. For example, if your ingestion URL is `https://YWNQbQSarRBsa-.ingest.grepr.ai/otlp`, then the endpoint for log events is that URL followed by `/v1/logs`, and the endpoint for spans is the same URL followed by `/v1/traces`. Each tab below states which form its sender expects. To see configuration examples for sending data to Grepr, select the tab for your collector or coding agent: The OpenTelemetry Collector can send logs to Grepr using the `otlphttp` exporter. In the OpenTelemetry collector configuration, set the endpoint to the ingestion URL from your OpenTelemetry integration: ```yaml exporters: otlphttp: endpoint: headers: x-grepr-token: service: pipelines: logs: receivers: [otlp] processors: [batch] exporters: [otlphttp] ``` Replace: * `` with the ingestion URL from your OpenTelemetry integration. * `` with the token from your OpenTelemetry integration. For dual shipping, you need to create two exporters: one to send logs to Grepr, and another to send logs directly to your vendor's platform. Your exporter for Grepr only includes Grepr's ingestion endpoint, with any needed headers configured in the Grepr UI. Your exporter for the vendor's platform includes the vendor's endpoint and the necessary headers. ```yaml exporters: otlphttp/grepr: endpoint: headers: x-grepr-token: otlphttp/vendor: endpoint: headers: authorization: "Bearer " service: pipelines: logs: receivers: [otlp] processors: [batch] exporters: [otlphttp/grepr, otlphttp/vendor] ``` Replace: * `` with the ingestion URL from your OpenTelemetry integration. * `` with the token from your OpenTelemetry integration. * `` with your vendor's OTLP/HTTP endpoint URL. * `` with your vendor's authentication token. To learn more about configuration settings for the OpenTelemetry Collector, see the [OTLP/HTTP Exporter documentation](https://github.com/open-telemetry/opentelemetry-collector#readme). Similar to log forwarding, the OpenTelemetry Collector can send APM events to Grepr using the `otlphttp` exporter. In your collector configuration, add a `traces` pipeline that uses the `otlphttp` exporter. The exporter appends the path `/v1/traces` to the ingestion URL. ```yaml exporters: otlphttp: endpoint: headers: x-grepr-token: service: pipelines: logs: receivers: [otlp] processors: [batch] exporters: [otlphttp] traces: receivers: [otlp] processors: [batch] exporters: [otlphttp] ``` Replace: * `` with the ingestion URL from your OpenTelemetry integration. * `` with the token from your OpenTelemetry integration. Fluent Bit can forward logs to Grepr using the OpenTelemetry output plugin. To configure the plugin: * Set the `host` value using only the hostname of the ingestion URL from your OpenTelemetry integration, omitting the `https://` prefix and the path value. * Set the `logs_uri` value to the ingestion URL path and append `/v1/logs`. * Add a `header` entry that sends the Grepr token as `x-grepr-token`. For example, if your ingestion URL is `https://YWNQbQSarRBsa-.ingest.grepr.ai/otlp`, set the `host` value to `YWNQbQSarRBsa-.ingest.grepr.ai` and the `logs_uri` value to `/otlp/v1/logs`. The following is an example `OUTPUT` configuration for the OpenTelemetry plugin from a Fluent Bit configuration file (`fluent-bit.conf`): ```fluent [OUTPUT] name opentelemetry match * host -.ingest.grepr.ai port 443 logs_uri /otlp/v1/logs header x-grepr-token tls On tls.verify On ``` To learn more about configuration settings for Fluent Bit, see the documentation for the [Fluent Bit OpenTelemetry output plugin](https://docs.fluentbit.io/manual/data-pipeline/outputs/opentelemetry). Claude Code exports its own telemetry over OTLP. It reports prompts, assistant responses, tool calls, token counts, and cost as OTLP log events, and reports each interaction, model request, and tool execution as OTLP spans. An agent sessions pipeline reads both signals, so set a logs endpoint and a traces endpoint. * `CLAUDE_CODE_ENABLE_TELEMETRY` turns on telemetry and is required. * `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` turns on spans. Without it, Claude Code exports no traces, and a session has no execution spans and no timing waterfall. * `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_ASSISTANT_RESPONSES`, and `OTEL_LOG_TOOL_DETAILS` record prompt text, response text, and tool arguments. Without them, Claude Code redacts the content and a transcript shows metadata only. * `OTEL_LOG_TOOL_CONTENT` records what each tool returned. Claude Code reports tool output only on a span event, so this setting requires spans. * `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` each take the full path for their signal, so append `/v1/logs` and `/v1/traces` to the ingestion URL. * `OTEL_EXPORTER_OTLP_HEADERS` carries the Grepr token and applies to both signals. * `OTEL_METRICS_EXPORTER` is set to `none` because an agent sessions pipeline reads logs and traces only. The following example exports the settings and then starts Claude Code: ```bash export CLAUDE_CODE_ENABLE_TELEMETRY=1 export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 export OTEL_LOGS_EXPORTER=otlp export OTEL_TRACES_EXPORTER=otlp export OTEL_METRICS_EXPORTER=none export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=/v1/logs export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=/v1/traces export OTEL_EXPORTER_OTLP_HEADERS="x-grepr-token=" export OTEL_LOG_USER_PROMPTS=1 export OTEL_LOG_ASSISTANT_RESPONSES=1 export OTEL_LOG_TOOL_DETAILS=1 export OTEL_LOG_TOOL_CONTENT=1 claude ``` Replace: * `` with the ingestion URL from your OpenTelemetry integration. * `` with the token from your OpenTelemetry integration. > Claude Code truncates prompts, responses, and tool content at 60 KB. Grepr labels shortened content as a truncated capture in the transcript. To raise the limit, set `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` to a larger value. To learn more about the settings Claude Code supports, see [Monitoring usage](https://code.claude.com/docs/en/monitoring-usage). To learn what an agent session contains and how to build the pipeline that captures one, see [Capture and explore agent sessions](https://docs.grepr.ai/pipelines/agent-sessions). Codex exports its own telemetry over OTLP. It reports prompts, tool results, and token counts as OTLP log events named `codex.*`, and reports turns, model responses, and command executions as OTLP spans. Codex selects a separate exporter for each signal, so configure both. * `otel.exporter` selects the exporter for log events. * `otel.trace_exporter` selects the exporter for spans. Without it, Codex exports no spans, and a session has no execution spans and no timing waterfall. * Each endpoint must include the path for its signal, `/v1/logs` for log events and `/v1/traces` for spans. Codex sends to the endpoint you configure without appending a path. * `otel.metrics_exporter` is set to `none` because an agent sessions pipeline reads logs and traces only. The default sends metrics to Statsig. * `otel.log_user_prompt` records prompt text. Without it, Codex omits the prompt and a transcript shows metadata only. The following example is a snippet from the Codex configuration file, `~/.codex/config.toml`: ```ini [otel] environment = "production" log_user_prompt = true metrics_exporter = "none" [otel.exporter.otlp-http] endpoint = "/v1/logs" protocol = "binary" headers = { "x-grepr-token" = "" } [otel.trace_exporter.otlp-http] endpoint = "/v1/traces" protocol = "binary" headers = { "x-grepr-token" = "" } ``` Replace: * `` with the ingestion URL from your OpenTelemetry integration. * `` with the token from your OpenTelemetry integration. > Codex reports a different service name for each of its binaries, `codex_exec` when you run `codex exec` and `codex_cli_rs` when you run the interactive CLI. Grepr recognizes both, so sessions from either binary appear together. To learn more about the settings Codex supports, see the [Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference). To learn what an agent session contains and how to build the pipeline that captures one, see [Capture and explore agent sessions](https://docs.grepr.ai/pipelines/agent-sessions). OpenCode reports agent activity through an OpenTelemetry plugin, which exports prompts, assistant responses, tool calls, tool results, token counts, and cost as OTLP spans. Register the plugin in your OpenCode configuration and then point it at your ingestion URL. * The `plugin` array in your OpenCode configuration loads `@devtheops/opencode-plugin-otel`. Pin the version so a later release cannot change what the plugin reports. * `OPENCODE_ENABLE_TELEMETRY` turns on the plugin's export and is required. * `OPENCODE_OTLP_ENDPOINT` is the ingestion URL without a signal path. The plugin appends the path itself. * `OPENCODE_OTLP_HEADERS` carries the Grepr token as a comma-separated list of `key=value` pairs. * `OPENCODE_DISABLE_LOGS` stops the plugin exporting log records. The plugin reports a whole session on spans, so its log records are not part of an agent session. * Leave the standard `OTEL_` variables unset. They turn on OpenCode's built-in instrumentation, which reports internal runtime operations such as `sql.execute` rather than agent activity. The following example registers the plugin, exports the settings, and then starts OpenCode: ```bash cat > opencode.json <<'JSON' { "plugin": ["@devtheops/opencode-plugin-otel@1.4.0"] } JSON export OPENCODE_ENABLE_TELEMETRY=1 export OPENCODE_OTLP_ENDPOINT= export OPENCODE_OTLP_HEADERS="x-grepr-token=" export OPENCODE_OTLP_PROTOCOL=http/protobuf export OPENCODE_DISABLE_LOGS=1 opencode ``` Replace: * `` with the ingestion URL from your OpenTelemetry integration. * `` with the token from your OpenTelemetry integration. > The plugin also exports metrics, which an agent sessions pipeline does not read. To stop exporting them, set `OPENCODE_DISABLE_METRICS` to a comma-separated list of the metric names you want to disable. The setting matches each name exactly and has no single value that disables all of them. To learn what an agent session contains and how to build the pipeline that captures one, see [Capture and explore agent sessions](https://docs.grepr.ai/pipelines/agent-sessions). ## Use an OTLP/HTTP compatible vendor integration in a Grepr pipeline \[#vendor-otel-configuration] The following tabs show the integration configurations required to connect Grepr to an observability vendor's OTLP/HTTP endpoint. To connect to a vendor not listed here: 1. In your vendor's documentation, find their OTLP/HTTP endpoint URL and any required authentication headers. 2. Create an OpenTelemetry integration in Grepr using your vendor's endpoint URL and headers. For instructions, see [_](#step1-create-integration). 3. Configure your collector to send data to Grepr. For instructions, see [_](#configure-forwarding-to-grepr). To send OpenTelemetry data to Datadog from Grepr, configure your integration to use the Datadog OTLP endpoint and required headers. **Integration Configuration:** * **Endpoint URL**: `https://http-intake.logs.datadoghq.com/api/v2/logs` * **Headers**: * `dd-protocol`: `otlp` * **Secret Headers**: * `dd-api-key`: `` Replace `` with your Datadog API key. For more information, see [Datadog OTLP Logs Intake Endpoint](https://docs.datadoghq.com/opentelemetry/setup/intake_endpoint/otlp_logs/). To use Grepr's native Datadog integration instead of OpenTelemetry, see [Configure Datadog connections with a Grepr integration](/integrations/datadog). To send OpenTelemetry data to Sumo Logic from Grepr, configure your integration to use the Sumo Logic OTLP/HTTP source endpoint. **Integration Configuration:** * **Endpoint URL**: Your Sumo Logic OTLP/HTTP source URL. For example, `https://collectors.sumologic.com/receiver/v1/otlp/`. Replace `` with the unique identifier from your Sumo Logic OTLP/HTTP source. For more information, see [Sumo Logic's OTLP documentation](https://help.sumologic.com/docs/send-data/hosted-collectors/http-source/otlp/). To use Grepr's native Sumo Logic integration instead of OpenTelemetry, see [Configure Sumo Logic connections with a Grepr integration](/integrations/sumo-logic). To send OpenTelemetry data to Grafana Cloud from Grepr, configure your integration to use the Grafana Cloud OTLP endpoint and an access policy token. **Integration Configuration:** * **Endpoint URL**: Your Grafana Cloud OTLP endpoint. For example, `https://otlp-gateway-prod-us-west-0.grafana.net/otlp`. * **Secret Headers**: * `Authorization`: `Bearer ` Generate the Grafana access token from a Grafana Cloud Access Policy with write access to logs. To create a token, in your Grafana Cloud account, go to **Home > Administration > Users and access > Cloud access policies**. For detailed setup instructions, including configuration examples for Grafana Alloy, the OpenTelemetry Collector, and the Grafana Agent, see [_](/integrations/grafana). To send OpenTelemetry data to Amazon CloudWatch from Grepr, configure your integration to use the CloudWatch OTLP/HTTP endpoint, bearer token authentication, and JSON encoding. **Integration Configuration:** * **Endpoint URL**: `https://logs..amazonaws.com` * **Secret Headers**: * `Authorization`: `Bearer ` * **Headers**: * `x-aws-log-group`: `` * `x-aws-log-stream`: `` * **Output encoding**: `JSON` The log group must have bearer token authentication enabled and the log stream must exist before you send logs. To learn more about integrating Grepr with CloudWatch, including configuration examples, see [_](/integrations/cloudwatch). ## Security considerations Grepr validates all headers you configure on an OpenTelemetry integration for potential security issues, including CRLF injection, control characters, and other attacks. Otherwise, when configuring OpenTelemetry integrations: * Always use secret headers for sensitive information like API keys, tokens, or passwords. * Ensure endpoint URLs use HTTPS for secure data transmission. * Avoid using reserved headers. Some HTTP headers are reserved and cannot be set for security reasons. * Send the Grepr token in the `x-grepr-token` header rather than in the ingestion URL. Proxies, load balancers, and request logs commonly record full URLs, so a token in a URL can be retained well outside your control. ## Frequently Asked Questions ### How do I create an OpenTelemetry integration with Grepr? In the Grepr UI, go to Integrations and click Add new. Select OpenTelemetry, enter a name, and provide the URL for your vendor's OTLP/HTTP endpoint. Optionally add HTTP headers for authentication. After creation, Grepr generates a token that your collector must send in the x-grepr-token header to the ingestion endpoint. ### What is the purpose of the Grepr token in OpenTelemetry integrations? The Grepr token is automatically generated during OpenTelemetry integration creation and is required for authentication. It ensures that only authorized collectors can send data to your Grepr pipeline. Send it in the x-grepr-token header on requests to your ingestion URL, https\://\-\.ingest.grepr.ai/otlp. ### Can I use OpenTelemetry integration with any observability vendor? Yes, the OpenTelemetry integration works with any vendor that accepts the OpenTelemetry Protocol (OTLP) over HTTP. This includes Grafana Cloud, Sumo Logic with OTLP source, Datadog, and many others. Check your vendor's documentation for their OTLP/HTTP endpoint URL. ### How do I configure the OpenTelemetry Collector to send logs to Grepr? Configure the otlphttp exporter in your collector.yaml with the Grepr ingestion endpoint. Set the endpoint to https\://\-\.ingest.grepr.ai/otlp and add a headers entry setting x-grepr-token to your Grepr token. Add the exporter to your logs pipeline along with your receivers and processors. ### How do I send traces to Grepr with an OpenTelemetry integration? Add a traces pipeline to your OpenTelemetry Collector configuration that uses the same otlphttp exporter as your logs pipeline, with the endpoint set to your Grepr ingestion URL. The exporter sends trace data to the /v1/traces path under the ingestion URL. ### How do I set up dual-shipping with OpenTelemetry integration? Create two exporters in your OpenTelemetry Collector configuration: one otlphttp/grepr pointing to your Grepr ingestion endpoint, and another otlphttp/vendor pointing to your vendor's OTLP endpoint with appropriate headers. Include both in your logs pipeline to send logs to both destinations. ### What headers do I need for OpenTelemetry integration with Datadog? For Datadog, configure the integration with the endpoint https\://http-intake.logs.datadoghq.com/api/v2/logs. Add a dd-protocol header set to otlp, and add a dd-api-key header set to your Datadog API key. Store the API key securely by clicking the lock icon when you add the header. ### How do I send logs to Sumo Logic via OpenTelemetry integration? Configure the integration with your Sumo Logic OTLP/HTTP source URL, for example, https\://collectors.sumologic.com/receiver/v1/otlp/\. Replace \ with the unique identifier from your Sumo Logic OTLP/HTTP source. ### How do I protect sensitive headers in OpenTelemetry integrations? Click the lock icon for any header that contains a sensitive value such as an API key, token, or password. Grepr stores these values securely and masks them in the UI. Do not include sensitive information in non-secret headers. ### What OpenTelemetry collectors are supported with Grepr? Grepr's OpenTelemetry integration works with any collector that supports the otlphttp exporter and can send to OTLP/HTTP endpoints. This includes the OpenTelemetry Collector, Fluent Bit, and Grafana Alloy. ### How do I send logs to Amazon CloudWatch with an OpenTelemetry integration? Configure the integration with the endpoint https\://logs.\.amazonaws.com and add three headers: an Authorization header set to Bearer \ and stored securely with the lock icon, an x-aws-log-group header set to your log group name, and an x-aws-log-stream header set to your log stream name. Set Output encoding to JSON. You must enable bearer token authentication on the CloudWatch log group and create the log stream before sending logs.