Hanzo Console - AI Observability and Prompt Management
Category: Hanzo Ecosystem
Related Skills: hanzo/hanzo-chat.md, hanzo/hanzo-cloud.md, hanzo/python-sdk.md
Overview
Hanzo Console is the observability and prompt management layer for AI applications. Fork of Langfuse. Captures traces, scores, datasets, and prompts from any LLM application. Provides a dashboard for debugging, evaluation, and cost analysis. Compatible with the Langfuse SDK and OpenTelemetry. Live at console.hanzo.ai.
When to use
- Tracing and debugging LLM calls, tool use, and agent steps
- Cost attribution per-request, per-user, per-model
- Managing prompt versions and deployments
- Building evaluation datasets and running automated scoring
- Monitoring AI application performance and latency
Hard requirements
- API Key required: Use
HANZO_API_KEY or Langfuse pair LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY
- Never expose keys in user-visible output, logs, or screenshots
- Traces are async: SDK batches in background. Call
flush() before process exit
- PostgreSQL backend: Console uses
console database on postgres.hanzo.svc
Quick reference
| Item |
Value |
| Dashboard |
https://console.hanzo.ai |
| API Base |
https://console.hanzo.ai/api |
| Langfuse host |
https://console.hanzo.ai |
| Ingestion API |
https://console.hanzo.ai/api/public/ingestion |
| Auth (Hanzo) |
Authorization: Bearer ${HANZO_API_KEY} |
| Auth (Langfuse) |
Basic auth with public/secret key pair |
| Upstream |
Langfuse |
| Repo |
github.com/hanzoai/console |
| K8s manifests |
universe/infra/k8s/console/ |
| Image |
ghcr.io/hanzoai/console:main |
| Worker Image |
ghcr.io/hanzoai/console-worker:main |
| Port |
3000 (web), 3030 (worker) |
| IAM Client ID |
hanzo-console |
| Worker health |
/api/health (NOT /api/public/health) |
Recent Changes (2026-03-28)
- Tracking embed + product keys section added to console settings
- Worker readiness/liveness probes fixed: path
/api/public/health → /api/health
- IAM OAuth provider registered (env:
IAM_CLIENT_ID, IAM_CLIENT_SECRET, IAM_SERVER_URL)
Architecture
Cloud API (cloud.hanzo.ai) POSTs traces to Console's ingestion endpoint for centralized observability.
Python quickstart (Langfuse SDK)
Python quickstart (Hanzo SDK decorator)
Python quickstart (OpenAI drop-in)
API reference
Traces
| Method |
Endpoint |
Purpose |
| POST |
/api/public/traces |
Create trace |
| GET |
/api/public/traces/{id} |
Get trace |
| GET |
/api/public/traces |
List traces |
Generations (LLM calls)
| Method |
Endpoint |
Purpose |
| POST |
/api/public/generations |
Create generation |
| PATCH |
/api/public/generations/{id} |
Update generation |
| GET |
/api/public/generations |
List generations |
Scores
| Method |
Endpoint |
Purpose |
| POST |
/api/public/scores |
Create score |
| GET |
/api/public/scores |
List scores |
Prompts
| Method |
Endpoint |
Purpose |
| POST |
/api/public/prompts |
Create prompt |
| GET |
/api/public/prompts/{name} |
Get prompt (latest) |
| GET |
/api/public/prompts/{name}/{version} |
Get prompt version |
| GET |
/api/public/prompts |
List prompts |
Datasets
| Method |
Endpoint |
Purpose |
| POST |
/api/public/datasets |
Create dataset |
| GET |
/api/public/datasets |
List datasets |
| POST |
/api/public/dataset-items |
Create dataset item |
| POST |
/api/public/dataset-run-items |
Create dataset run |
Prompt management
Version, test, and deploy prompts from a central registry:
Prompt lifecycle
- Create: Author prompt in Console dashboard or via API
- Version: Each edit creates a new immutable version
- Label: Mark versions as
production, staging, latest
- Deploy: SDK fetches by label; no code change needed
- Evaluate: A/B test prompt versions against datasets
Multi-org bootstrap
Console supports multi-org provisioning on startup:
K8s deployment
Error handling
| Code |
Meaning |
Action |
| 200 |
Success |
Process response |
| 400 |
Bad request |
Check trace/generation format |
| 401 |
Unauthorized |
Check API keys or Langfuse credentials |
| 404 |
Not found |
Check trace/prompt/dataset ID |
| 429 |
Rate limited |
SDK auto-retries; manual calls should back off |
| 500 |
Server error |
Retry up to 3 times |
Related Skills
hanzo/hanzo-cloud.md -- Cloud API (sends traces to Console)
hanzo/hanzo-chat.md -- Chat app (auto-instrumented)
hanzo/hanzo-o11y.md -- Infrastructure observability (Hanzo o11y)
hanzo/python-sdk.md -- Python SDK with @observe() decorator
Last Updated: 2026-03-23
Category: Hanzo Ecosystem
Related: observability, tracing, prompts, evaluation, langfuse, cost-tracking
Prerequisites: Python or Node.js, Langfuse SDK or Hanzo SDK