​
Overview

OpenTelemetry Protocol (OTLP) is a vendor-neutral, industry-standard telemetry format for transmitting trace data. Maxim provides OTLP ingestion capabilities for both AI and LLM Observability, enabling deep insights into your AI systems.

​
Before you begin

Ensure you have created a Log Repository in Maxim and have your Log Repository ID ready. You can find it in the Maxim Dashboard under Logs > Repositories.

​
Endpoint & Protocol Configuration

Endpoint: https://api.getmaxim.ai/v1/otel

Supported Protocols: HTTP with OTLP binary Protobuf or JSON

ProtocolContent-Type
HTTP + Protobuf (binary)application/x-protobuf or application/protobuf
HTTP + JSONapplication/json

Transport Security:

  • HTTPS/TLS is required.

​
Authentication Headers

Maxim’s OTLP endpoint requires the following headers:

  • x-maxim-repo-id: Your Maxim Log Repository ID
  • x-maxim-api-key: Your Maxim API Key
  • Content-Type: application/json, application/x-protobuf, or application/protobuf

​
Supported Trace Format

Maxim currently supports traces that follow the OpenTelemetry Semantic Conventions for Generative AI (specification).

​
Best Practices

  • Use binary Protobuf (application/x-protobuf) for optimal performance and robustness
  • Batch traces to reduce network overhead
  • Include rich attributes following GenAI semantic conventions
  • Secure your headers and avoid exposing credentials
  • Monitor attribute size limits and apply appropriate quotas

​
Error Codes and Responses

HTTP StatusConditionDescription
200Success{ "data": { "success": true } }
403Missing or invalid headers - x-maxim-repo-id or x-maxim-api-key{ "code": 403, "message": "Invalid access error" }

​
Code Examples

​
Python Example

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry import trace as trace_api

# Replace with your actual Maxim API key
maxim_api_key = "your_api_key_here"
# Replace with your actual repository ID
repo_id = "your_repository_id_here"

tracer_provider = trace_sdk.TracerProvider()
span_exporter = OTLPSpanExporter(
    endpoint="https://api.getmaxim.ai/v1/otel",
    headers={
        "x-maxim-api-key": f"{maxim_api_key}",
        "x-maxim-repo-id": f"{repo_id}",
    },
)

# Register the exporter
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
# Make it the global provider
trace_api.set_tracer_provider(tracer_provider)