Traces API

MiniAPM accepts traces via the OpenTelemetry Protocol (OTLP) over HTTP.

Endpoint

POST /ingest/v1/traces

Headers

Header	Required	Description
Authorization	Yes	Bearer <api_key>
Content-Type	Yes	application/json or application/x-protobuf

Request Format

MiniAPM accepts OTLP traces in both JSON and Protobuf formats. Use any OpenTelemetry SDK configured for HTTP export.

OTLP JSON Example

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "my-app" } }
        ]
      },
      "scopeSpans": [
        {
          "scope": { "name": "my-app" },
          "spans": [
            {
              "traceId": "5b8aa5a2d2c872e8321cf37308d69df2",
              "spanId": "051581bf3cb55c13",
              "name": "GET /api/users",
              "kind": 2,
              "startTimeUnixNano": "1704067200000000000",
              "endTimeUnixNano": "1704067200100000000",
              "attributes": [
                { "key": "http.method", "value": { "stringValue": "GET" } },
                { "key": "http.status_code", "value": { "intValue": 200 } }
              ],
              "status": { "code": 1 }
            }
          ]
        }
      ]
    }
  ]
}

Response

Success (200)

{
  "partialSuccess": {}
}

Error (400)

{
  "error": "Invalid trace format"
}

SDK Configuration

Ruby (miniapm gem)

The miniapm gem handles everything automatically:

gem 'miniapm'

MiniAPM.configure do |config|
  config.endpoint = "http://localhost:3000"
  config.api_key = "proj_abc123..."
end

OpenTelemetry Ruby SDK

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'http://localhost:3000/ingest/v1/traces',
        headers: { 'Authorization' => 'Bearer proj_abc123...' }
      )
    )
  )
end

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

exporter = OTLPSpanExporter(
    endpoint="http://localhost:3000/ingest/v1/traces",
    headers={"Authorization": "Bearer proj_abc123..."}
)

Node.js

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const exporter = new OTLPTraceExporter({
  url: 'http://localhost:3000/ingest/v1/traces',
  headers: {
    'Authorization': 'Bearer proj_abc123...'
  }
});

Go

import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"

exporter, err := otlptracehttp.New(ctx,
    otlptracehttp.WithEndpoint("localhost:3000"),
    otlptracehttp.WithURLPath("/ingest/v1/traces"),
    otlptracehttp.WithHeaders(map[string]string{
        "Authorization": "Bearer proj_abc123...",
    }),
)

Environment Variables

Most OpenTelemetry SDKs support environment-based configuration:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/ingest
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer proj_abc123...
export OTEL_SERVICE_NAME=my-app

Span Attributes

MiniAPM recognizes standard OpenTelemetry semantic conventions:

HTTP

• http.method - HTTP method (GET, POST, etc.)
• http.url - Full URL
• http.route - Route pattern
• http.status_code - Response status
• http.request_id - Request ID

Database

• db.system - Database type (postgresql, mysql, etc.)
• db.statement - Query (sanitized)
• db.operation - Operation type

Custom

Add any custom attributes:

MiniAPM.span("process_order") do |span|
  span.add_attribute("order.id", 123)
  span.add_attribute("order.total", 99.99)
end

W3C Trace Context

MiniAPM supports W3C Trace Context for distributed tracing. Include the traceparent header in your requests to continue traces across services:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01