OpenTelemetry API methods, requests, and responses for RawTree Cloud and RawTree BYOC.

OpenTelemetry

Install the OpenTelemetry app first. Exports require write permission.

The service accepts native OpenTelemetry Protocol ingest over OTLP/HTTP and OTLP/gRPC. For setup instructions, SDK environment variables, Collector config, and a smoke test, see the OpenTelemetry guide.

The OpenTelemetry app must be installed on the target cluster before these native endpoints can be used. The generic table insert transforms, such as POST /v1/tables/traces?transform=otlp-traces, do not require the app.

Both paths apply the built-in OpenTelemetry transforms and write to the default signal tables.

Native OTLP endpoints write to the default traces, logs, and metrics tables unless you provide a signal-specific destination header: x-rawtree-traces-table, x-rawtree-logs-table, or x-rawtree-metrics-table. For OTLP/HTTP, select the database with the database query parameter. For OTLP/gRPC, use the x-rawtree-database metadata header. If the request omits a selector, the service uses the API key's stored default database.

POST `/otlp/v1/traces`

Ingest OTLP/HTTP traces into the traces table, or into the table named by x-rawtree-traces-table.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Install the OpenTelemetry app first. Send OTLP JSON with application/json or encoded Protobuf with application/x-protobuf. The response uses the same encoding. A successful HTTP status can still contain partialSuccess. Check its rejected count and error message.

Request:

# Export OpenTelemetry traces.
curl -X POST "https://api.rawtree.com/otlp/v1/traces?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "api-example"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "5B8EFFF798038103D269B633813FC60C",
              "spanId": "EEE19B7EC3C1B174",
              "name": "page view",
              "startTimeUnixNano": "1794218400000000000",
              "endTimeUnixNano": "1794218400001000000"
            }
          ]
        }
      ]
    }
  ]
}'

Expected response: HTTP 200.

{}

POST `/otlp/v1/logs`

Ingest OTLP/HTTP logs into the logs table, or into the table named by x-rawtree-logs-table.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Export OpenTelemetry logs.
curl -X POST "https://api.rawtree.com/otlp/v1/logs?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "api-example"
            }
          }
        ]
      },
      "scopeLogs": [
        {
          "logRecords": [
            {
              "timeUnixNano": "1794218400000000000",
              "severityText": "INFO",
              "body": {
                "stringValue": "service started"
              }
            }
          ]
        }
      ]
    }
  ]
}'

Expected response: HTTP 200.

{}

POST `/otlp/v1/metrics`

Ingest OTLP/HTTP metrics into the metrics table, or into the table named by x-rawtree-metrics-table.

These endpoints accept application/json and application/x-protobuf OTLP export payloads. Successful requests normally return an empty OTLP export response: {} for JSON requests or an empty protobuf message for protobuf requests. If the service accepts the export but drops invalid signal records, the response uses the OTLP partialSuccess shape with rejectedSpans, rejectedLogRecords, or rejectedDataPoints plus an errorMessage.

OTLP/HTTP request bodies can be gzip-compressed with Content-Encoding: gzip. Request bodies are limited to 100 MiB after decompression; larger exports return 413.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Export OpenTelemetry metrics.
curl -X POST "https://api.rawtree.com/otlp/v1/metrics?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceMetrics": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "api-example"
            }
          }
        ]
      },
      "scopeMetrics": [
        {
          "metrics": [
            {
              "name": "active_sessions",
              "gauge": {
                "dataPoints": [
                  {
                    "timeUnixNano": "1794218400000000000",
                    "asInt": "3"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}'

Expected response: HTTP 200.

{}

OTLP/gRPC

Send OTLP/gRPC export requests to the standard collector services:

Signal	Service
Traces	`opentelemetry.proto.collector.trace.v1.TraceService/Export`
Logs	`opentelemetry.proto.collector.logs.v1.LogsService/Export`
Metrics	`opentelemetry.proto.collector.metrics.v1.MetricsService/Export`

Use https://api.rawtree.com as the OTLP endpoint, or http://localhost:4317 with the local Docker Compose stack.

Use bearer authentication with a cluster API key:

Authorization: Bearer rt_...

gRPC traces export

# Use a descriptor set compiled from the OpenTelemetry protocol definitions.
# An empty export checks authentication without writing records.
grpcurl -protoset "$OTLP_DESCRIPTOR_SET" \
  -H "authorization: Bearer $RAWTREE_API_KEY" \
  -H "x-rawtree-database: analytics" \
  -d '{}' api.rawtree.com:443 \
  opentelemetry.proto.collector.trace.v1.TraceService/Export

Expected result: gRPC OK, with an empty export response.

{}

Check partialSuccess for rejected records on nonempty exports. Invalid credentials return UNAUTHENTICATED.

gRPC logs export

# Use a descriptor set compiled from the OpenTelemetry protocol definitions.
# An empty export checks authentication without writing records.
grpcurl -protoset "$OTLP_DESCRIPTOR_SET" \
  -H "authorization: Bearer $RAWTREE_API_KEY" \
  -H "x-rawtree-database: analytics" \
  -d '{}' api.rawtree.com:443 \
  opentelemetry.proto.collector.logs.v1.LogsService/Export

Expected result: gRPC OK, with an empty export response.

{}

Check partialSuccess for rejected records on nonempty exports. Invalid credentials return UNAUTHENTICATED.

gRPC metrics export

# Use a descriptor set compiled from the OpenTelemetry protocol definitions.
# An empty export checks authentication without writing records.
grpcurl -protoset "$OTLP_DESCRIPTOR_SET" \
  -H "authorization: Bearer $RAWTREE_API_KEY" \
  -H "x-rawtree-database: analytics" \
  -d '{}' api.rawtree.com:443 \
  opentelemetry.proto.collector.metrics.v1.MetricsService/Export

Expected result: gRPC OK, with an empty export response.

{}

Check partialSuccess for rejected records on nonempty exports. Invalid credentials return UNAUTHENTICATED.

OpenTelemetry

On this page