Traces API

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

Endpoint

POST /ingest/v1/traces

Headers

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

Request Format

MiniAPM accepts OTLP traces in JSON format. 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 (202 Accepted)

Returns 202 Accepted with no response body on success.

Error (500)

Returns 500 Internal Server Error if ingestion fails.

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 or url.full - Full URL
• http.status_code - Response status

Database

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

Search

• db.system - elasticsearch or opensearch

Messaging

• messaging.system - Messaging system name
• messaging.destination.name - Destination name

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