OpenTelemetry Integration¶

Pisama ingests standard OTLP/HTTP traces. Any service or framework that emits OpenTelemetry spans can send data to Pisama with no custom SDK.

Ingest endpoint¶

POST https://api.pisama.ai/api/v1/tenants/{tenant_id}/traces/ingest
Content-Type: application/json
Authorization: Bearer <api-key>

The body is a standard OTLP JSON export (ResourceSpans envelope). All OpenTelemetry SDKs can target this endpoint directly.

Java / Spring services (gRPC bridge)¶

The Java OpenTelemetry SDK defaults to gRPC on port 4317. Pisama accepts HTTP only. The recommended path is a thin OTel Collector that receives gRPC from your services and forwards to Pisama over HTTP — no code changes required.

Ready-to-run collector config:

deploy/otel-collector/revinate.yaml

View on GitHub

Quick start:

export PISAMA_TENANT_ID=<your-tenant-id>
export PISAMA_API_TOKEN=<your-api-key>
export PISAMA_API_URL=https://api.pisama.ai

docker run \
  -e PISAMA_TENANT_ID \
  -e PISAMA_API_TOKEN \
  -e PISAMA_API_URL \
  -v $(pwd)/revinate.yaml:/etc/otelcol/config.yaml \
  -p 4317:4317 \
  -p 4318:4318 \
  otel/opentelemetry-collector-contrib

Configure your Java services to export to localhost:4317 (the default) and they route through the collector to Pisama automatically.

Agent identification¶

Pisama identifies agents from span attributes using a priority list. No custom annotations are required if your services use standard OTel resource attributes.

Default resolution order:

Priority	Attribute	Notes
1	`gen_ai.agent.name`	Explicit agent name
2	`gen_ai.agent.id`	Agent ID used as name
3	`gen_ai.agent.role`	Role used as name
4	`service.name`	Standard OTel resource attribute — Java/Spring default
5	`peer.service`
6	`span.name`	Fallback

A Spring service named generator-service will appear as generator-service in Pisama trace views and detection cards without any configuration.

Custom agent mappings¶

If your service names do not match the agent names you want in Pisama (e.g., rv-validator-svc should appear as validator), configure tenant-level mappings:

curl -X PUT https://api.pisama.ai/api/v1/tenants/{id}/settings/agent-mappings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "span_attribute": "service.name",
      "span_value": "rv-generator-svc",
      "agent_name": "generator"
    },
    {
      "span_attribute": "service.name",
      "span_value": "rv-validator-svc",
      "agent_name": "validator"
    }
  ]'

Mappings are checked before the default resolution order. Any span attribute can be used as the match key, not just service.name.

Read current mappings:

curl https://api.pisama.ai/api/v1/tenants/{id}/settings/agent-mappings \
  -H "Authorization: Bearer $TOKEN"

Environment separation¶

Tag spans with the standard OTel resource attribute deployment.environment to separate dev, staging, and production traces within a single tenant.

// Java example — set at SDK initialization
SdkTracerProvider.builder()
    .setResource(Resource.create(Attributes.of(
        ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "production"
    )))
    .build();

Pisama normalises the value to development, staging, or production. Filter any API call by environment:

# Only production detections
GET /api/v1/tenants/{id}/detections?environment=production

# Only staging traces
GET /api/v1/tenants/{id}/traces?environment=staging

Conversation grouping¶

Multi-turn agent sessions (a sequence of spans belonging to the same conversation) are grouped by gen_ai.conversation.id. Set this on all spans that belong to the same session:

span.setAttribute("gen_ai.conversation.id", sessionId);

Without this attribute, Pisama falls back to grouping by trace ID.

Grafana integration¶

Pisama exposes a Prometheus-compatible metrics endpoint and a ready-to-import Grafana dashboard.

# Prometheus scrape target
GET /api/v1/metrics
Authorization: Bearer <api-key>

# Ready-to-import Grafana dashboard JSON
GET /api/v1/metrics/grafana/dashboard
Authorization: Bearer <api-key>

Import the dashboard JSON via Grafana > Dashboards > Import > JSON model. Set DS_PROMETHEUS to your Prometheus instance. The dashboard includes panels for pisama_detections_total, per-detector F1, and detection latency.