OpenTelemetry

Raindrop consumes OpenTelemetry Protocol (OTLP) traces over HTTP. Send trace exports to:

https://api.raindrop.ai/v1/traces

The endpoint accepts OTLP/HTTP JSON and protobuf. Use Content-Type: application/json for JSON, or Content-Type: application/x-protobuf for protobuf. Gzip and deflate request-body compression are supported for protobuf through the standard Content-Encoding header. Send JSON exports uncompressed. This endpoint supports OTLP/HTTP only; OTLP/gRPC is not supported.

This endpoint ingests OTLP traces. OTLP metrics and logs are not accepted today.

Prerequisites

Get your write key by logging in to app.raindrop.ai. Send it as a bearer token:

Authorization: Bearer YOUR_WRITE_KEY

To route traces to a specific project, include its slug:

X-Raindrop-Project-Id: support-prod

If you omit this header, traces go to your organization’s default Production project. A malformed slug returns 400; an inactive or disallowed project returns 403. See the HTTP API reference for the full project behavior table.

Send a trace with curl

This sends one OTLP/HTTP JSON export with a model, token usage, input message, and output message:

curl https://api.raindrop.ai/v1/traces \
  -X POST \
  -H "Authorization: Bearer $RAINDROP_WRITE_KEY" \
  -H "X-Raindrop-Project-Id: support-prod" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "resourceSpans": [{
      "resource": {
        "attributes": [{
          "key": "service.name",
          "value": { "stringValue": "checkout-agent" }
        }]
      },
      "scopeSpans": [{
        "scope": {
          "name": "example"
        },
        "spans": [{
          "traceId": "0102030405060708090a0b0c0d0e0f10",
          "spanId": "0102030405060708",
          "name": "chat.completion",
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000",
          "attributes": [{
            "key": "gen_ai.system",
            "value": { "stringValue": "openai" }
          }, {
            "key": "gen_ai.response.model",
            "value": { "stringValue": "gpt-4o" }
          }, {
            "key": "gen_ai.usage.input_tokens",
            "value": { "intValue": "12" }
          }, {
            "key": "gen_ai.usage.output_tokens",
            "value": { "intValue": "8" }
          }, {
            "key": "gen_ai.input.messages",
            "value": {
              "stringValue": "[{\"role\":\"user\",\"content\":\"What is the weather today?\"}]"
            }
          }, {
            "key": "gen_ai.output.messages",
            "value": {
              "stringValue": "[{\"role\":\"assistant\",\"content\":\"It is sunny and warm.\"}]"
            }
          }]
        }]
      }]
    }]
  }'

The response is an OTLP ExportTraceServiceResponse in the same encoding as the request. For protobuf, send a protobuf-encoded ExportTraceServiceRequest body with Content-Type: application/x-protobuf. Compression can be enabled for protobuf by sending the encoded body with Content-Encoding: gzip (or deflate). JSON exports should be sent uncompressed.

OpenTelemetry Collector

Configure the Collector’s otlphttp exporter with the Raindrop endpoint and write key:

exporters:
  otlphttp/raindrop:
    endpoint: https://api.raindrop.ai
    encoding: proto
    headers:
      Authorization: "Bearer ${RAINDROP_WRITE_KEY}"
      X-Raindrop-Project-Id: "support-prod"
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: []
      exporters: [otlphttp/raindrop]

The standard OTLP/HTTP exporter appends /v1/traces to the endpoint. You can also set the exporter endpoint explicitly to https://api.raindrop.ai/v1/traces.

Standard OTLP environment variables

The standard OTLP environment variables are the language-agnostic way to configure an OTLP exporter:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.raindrop.ai/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20${RAINDROP_WRITE_KEY}"

%20 encodes the space after Bearer, which opentelemetry-python and other SDKs URL-decode when reading these variables.

OpenTelemetry SDKs

TypeScript

Use the OpenTelemetry OTLP/HTTP trace exporter:

pnpm add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { NodeSDK } from "@opentelemetry/sdk-node";

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: "https://api.raindrop.ai/v1/traces",
    headers: {
      Authorization: `Bearer ${process.env.RAINDROP_WRITE_KEY}`,
    },
  }),
});

sdk.start();

For a short-lived process, call await sdk.shutdown() after creating spans so the exporter flushes before exit.

Python

Use the standard OTLP environment variables above with the Python OTLP/HTTP exporter, keeping the %20 after Bearer.

Attributes Raindrop maps

These current GenAI semantic conventions populate the corresponding span and interaction fields:

gen_ai.system identifies the provider, and marks the span as an LLM call. Set it on every span you want treated as a generation.
gen_ai.response.model populates the model.
gen_ai.usage.input_tokens and gen_ai.usage.output_tokens populate token usage. Send both, alongside gen_ai.response.model.
gen_ai.input.messages and gen_ai.output.messages populate input and output messages. Use JSON arrays of message objects with role and content fields; content can be text or structured parts.
gen_ai.system_instructions populates system instructions.
ai.prompt.tools records the tools the model was given for the call: a string array with one JSON document per tool ({"type":"function","name","description","inputSchema"} or {"type":"provider-defined",...}). Add ai.prompt.tools.source when the list is a catalog rather than the exact per-request set. See Tool catalog capture.

Raindrop creates AI Events from eligible model spans that follow these conventions and carry the required metadata. These exports do not require SDK begin() or finish() calls.

Limits and troubleshooting

The default rate limit is 3,000 requests per sliding 60 seconds per write key. Organizations may have a different configured limit. When the endpoint returns 429, wait the number of seconds in Retry-After and retry with backoff. Batch spans through the Collector or SDK exporter rather than sending one request per span. The route treats application/json as OTLP/HTTP JSON and everything else, including a missing content type, as protobuf. Always set Content-Type explicitly. gzip and deflate are the supported Content-Encoding values; any other value, including zstd, returns 400. A request body that exceeds 32 MiB once decompressed returns 413.

Getting Started

SDK

Integrations

Platform

Organization

Cookbooks

Workshop

Query API

MCP

Security

Support

Prerequisites

Send a trace with curl

OpenTelemetry Collector

Standard OTLP environment variables

OpenTelemetry SDKs

TypeScript

Python

Attributes Raindrop maps

Limits and troubleshooting

​Prerequisites

​Send a trace with curl

​OpenTelemetry Collector

​Standard OTLP environment variables

​OpenTelemetry SDKs

​TypeScript

​Python

​Attributes Raindrop maps

​Limits and troubleshooting

Prerequisites

Send a trace with curl

OpenTelemetry Collector

Standard OTLP environment variables

OpenTelemetry SDKs

TypeScript

Python

Attributes Raindrop maps

Limits and troubleshooting