Skip to content

Quickstart

Get Pisama running and detecting failures in minutes. Choose your path:

Path 0: One detector in 30 seconds

The fastest way to feel Pisama work. No orchestration, no trace format, just a detector and a payload.

pip install pisama

import pisama

result = pisama.analyze({
    "trace_id": "demo",
    "spans": [{"name": "Read", "kind": "tool"} for _ in range(8)],
})
for issue in result.issues:
    print(issue.type, issue.severity, issue.summary)
# loop 100 Tool 'Read' repeated 8x consecutively

32 core detectors running offline. See Path A for the full trace analysis walkthrough.

Path A: Python SDK with trace analysis (3 minutes, no server)

Pass a full agent trace, get back every detected failure.

pip install pisama

import pisama

result = pisama.analyze("trace.json")
for issue in result.issues:
    print(f"[{issue.type}] {issue.summary}")

32 core detectors running offline at zero cost. See the SDK Quickstart for the full walkthrough.

Path B: Full Platform (5 minutes)

The platform adds a dashboard, ML detection, self-healing, and a REST API. See OSS vs Cloud for what each path gives you.

Hosted (recommended). Sign up at pisama.ai/sign-up, then get your API key from Settings / API Keys. Skip to Step 4 and replace localhost:8000 with https://api.pisama.ai.

Self-hosted. Follow Steps 1-3 below to run the full stack locally with Docker.

1. Start Pisama

git clone https://github.com/Pisama-AI/pisama.git
cd pisama
docker compose up

This starts PostgreSQL (pgvector), Redis, the FastAPI backend on port 8000, and the Next.js frontend on port 3000.

2. Verify the setup

curl http://localhost:8000/api/v1/health

Expected response (plus a version field):

{"status": "healthy", "database": "healthy", "redis": "healthy"}

3. Create a tenant and get an API key

curl -X POST http://localhost:8000/api/v1/auth/tenants \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "accepted_terms": true}'

Save the api_key and tenant_id from the response.

4. Exchange the API key for a JWT token

export TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}' | jq -r '.access_token')

5. Send a test trace

curl -X POST http://localhost:8000/api/v1/tenants/YOUR_TENANT_ID/traces/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "my-agent"}}
        ]
      },
      "scopeSpans": [{
        "spans": [
          {
            "traceId": "abc123",
            "spanId": "span001",
            "name": "agent_step_1",
            "kind": 1,
            "startTimeUnixNano": "1700000000000000000",
            "endTimeUnixNano": "1700000001000000000",
            "attributes": [
              {"key": "gen_ai.agent.name", "value": {"stringValue": "research-agent"}},
              {"key": "gen_ai.request.model", "value": {"stringValue": "claude-sonnet-4"}},
              {"key": "gen_ai.usage.prompt_tokens", "value": {"intValue": 1500}},
              {"key": "gen_ai.usage.completion_tokens", "value": {"intValue": 800}}
            ],
            "status": {"code": 1}
          }
        ]
      }]
    }]
  }'

6. Run detection

Ingestion already triggers detection in the background. To re-run it on demand, address the trace by its Pisama ID (a UUID), not the OTEL traceId you sent (abc123 is stored as the run's session_id). Fetch the ID, then analyze:

TRACE_ID=$(curl -s http://localhost:8000/api/v1/tenants/YOUR_TENANT_ID/traces \
  -H "Authorization: Bearer $TOKEN" | jq -r '.traces[] | select(.session_id=="abc123") | .id')

curl -X POST http://localhost:8000/api/v1/tenants/YOUR_TENANT_ID/traces/$TRACE_ID/analyze \
  -H "Authorization: Bearer $TOKEN"

The response includes the detected failures (detections) plus detectors_run, detectors_failed, detection_status, and detection_time_ms.

7. Explore the results

Open http://localhost:3000 and sign in. The sidebar navigation gives you three views into your results:

  • Dashboard -- Overview with detection counts, cost analytics, and recent issues. This is your main hub.
  • Runs -- Lists all ingested traces. Click any run to see a waterfall timeline of its execution, a flow graph of the agent steps, and the detections found in that run.
  • Detections -- Lists every detected failure across all traces. Click a detection to see what happened, the business impact, a suggested fix, and an option to trigger auto-healing.

From the Detection detail page, you can:

  • Trigger Healing to generate an auto-fix (with approval workflow for high-risk changes)
  • View the trace to see the exact execution steps that led to the failure
  • Mark as valid or false positive to improve detection accuracy over time

Next steps