{"id":99466,"plugin_id":"plugin_asdk_app_6af767a176dc8191b1ac69088ad7d196","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-16T18:17:40.263Z","digest":"60fd3a138e40025c4490cee3134fd986e072d8c207b335ce9e2c50acad2b193d","against":null,"payload":{"description":"Add Brizz telemetry to an AI application, or fix an app that is sending nothing or sending it wrong. Trigger when the user asks to install or set up the Brizz SDK, instrument an agent or LLM app, send their first session, wire a framework (LangChain, Vercel AI, Vercel eve, Agno, Strands, LiveKit, MCP servers, Google GenAI, Claude Code, Langfuse), attach users/organizations/events/feedback to sessions, or when a Brizz service shows no sessions, no user identity, or missing tool spans and the cause is upstream in their own code.","included_files":[],"name":"brizz-instrument","skill_md_contents":"---\nname: brizz-instrument\ndescription: Add Brizz telemetry to an AI application, or fix an app that is sending nothing or sending it wrong. Trigger when the user asks to install or set up the Brizz SDK, instrument an agent or LLM app, send their first session, wire a framework (LangChain, Vercel AI, Vercel eve, Agno, Strands, LiveKit, MCP servers, Google GenAI, Claude Code, Langfuse), attach users/organizations/events/feedback to sessions, or when a Brizz service shows no sessions, no user identity, or missing tool spans and the cause is upstream in their own code.\n---\n\n# Instrument an app with Brizz\n\nEverything else in Brizz assumes spans are arriving. This skill covers the step before that:\ngetting a codebase to emit them, and fixing it when what arrives is incomplete.\n\nWork against the **published docs** — they are public markdown, version-matched to what\nships, and the same source the dashboard's own setup flow reads from:\n\n```\nhttps://platform.brizz.dev/llms.txt              # index of every page, ~14 KB\nhttps://platform.brizz.dev/docs/<slug>.md        # one page, as markdown\nhttps://platform.brizz.dev/llms-full.txt         # all 142 pages inlined, ~460 KB\n```\n\nFetch `llms.txt`, then open the page for the user's actual stack. Two fetches, a few\nthousand tokens. This skill carries only what is stable across stacks and the mistakes that\ncost the most time.\n\nReach for `llms-full.txt` only when you need to search across the whole corpus at once — an\nerror string whose page you can't guess, or a term you want every mention of. It is the\nentire documentation set in one file, so read it from disk with a grep rather than pulling\nhalf a million characters into context.\n\n## Establish three things before writing code\n\n1. **Runtime** — Python 3.10+ or Node 18+. Decides the package *and* the failure mode below.\n2. **Framework** — plain provider clients, or LangChain, Vercel AI, Vercel eve, Agno,\n   Strands, LiveKit, an MCP server, Google GenAI, or an existing Langfuse tracer. Each has\n   its own page under `docs/sdks/`, and in Node several need explicit wiring that nothing\n   warns you about. Guessing here is how an install ends up silent.\n3. **Credential** — a workspace issues either a **Server DSN** or an **API key**, not both.\n   Ask which they were given; don't assume.\n\nThen find where AI calls actually happen — client construction and the request/response\nboundary. That boundary is what a session wraps.\n\n## Credential\n\n**Prefer the Server DSN when the workspace issues one.** It is a single string carrying the\ncredential, the ingestion endpoint, and the service name:\n\n```\nhttps://<credential>@<ingest-host>/<service-name>\n```\n\n```bash\nexport BRIZZ_DSN=\"https://<credential>@<ingest-host>/<service-name>\"\n```\n\n```python\nBrizz.initialize(dsn=os.environ[\"BRIZZ_DSN\"])          # Python\n```\n```typescript\nBrizz.initialize({ dsn: process.env.BRIZZ_DSN });      // Node\n```\n\nThere is no `app_name` with a DSN — the service name is already in the string. That is the\nwhole difference; sessions, users, and events are identical afterwards.\n\nWith an API key instead, set `BRIZZ_API_KEY` and pass the service name yourself as\n`app_name` / `appName`. Get it right on the first run: it is the name the service is known\nby in every later query, and changing it splits the history in two.\n\nA DSN contains a credential. Treat it like a password — environment variable only, never\ncommitted, never shipped to a browser.\n\n## Install and initialize\n\n```bash\npip install brizz        # Python 3.10+\nnpm install @brizz/sdk   # Node 18+\n```\n\n**Python — initialization order is load-bearing.** Auto-instrumentation hooks libraries at\nimport time, so `Brizz.initialize()` must run *before* you import them:\n\n```python\nimport os\nfrom brizz import Brizz\n\nBrizz.initialize(dsn=os.environ[\"BRIZZ_DSN\"])\n\nfrom openai import OpenAI          # after, always\n```\n\n**Node — the module list is load-bearing instead.** Hand Brizz the libraries explicitly and\nimport order stops mattering:\n\n```typescript\nimport 'dotenv/config';\nimport { Brizz } from '@brizz/sdk';\nimport OpenAI from 'openai';\n\nBrizz.initialize({\n  dsn: process.env.BRIZZ_DSN,\n  instrumentModules: { openAI: OpenAI },   // every AI library the app uses\n});\n```\n\nThese are two different rules, and applying the Python one to Node wastes time on import\norder while the real cause is a library missing from `instrumentModules`. Both fail the same\nway from the outside: the app runs, nothing errors, no spans appear.\n\nWith `dotenv`, load the environment *before* importing the SDK — `load_dotenv()` first in\nPython, `import 'dotenv/config'` first in Node — or the credential reads as empty.\n\n## Wrap a session\n\nA session is the unit of analysis in the dashboard. Group an interaction into one:\n\n```python\nfrom brizz import start_session\n\nwith start_session(\"session-123\"):\n    ...\n```\n```typescript\nimport { withSessionId } from '@brizz/sdk';\n\nawait withSessionId('session-123', runAgent)();\n```\n\n## Framework wiring that is not automatic\n\nIn Python most frameworks instrument themselves once `initialize()` runs. Node is where\nthings need saying out loud — check the framework's page, and expect one of these:\n\n| Stack | What it needs |\n|---|---|\n| Vercel AI SDK | `experimental_telemetry: { isEnabled: true }` on each `generateText` / `streamText` call |\n| LangChain (JS) | `instrumentModules: { langchain: { callbackManagerModule } }` |\n| Google GenAI | Build the client from `instrumentGoogleGenAI(genai)` — `@google/genai` is ESM-only, so `instrumentModules` does not apply |\n| Vercel eve | Register Brizz in `instrumentation.ts`, with `BRIZZ_DSN` set |\n| Claude Code | No SDK — it emits OpenTelemetry natively, configured with environment variables |\n| Browser | `@brizz/browser` and a **client** DSN. The server SDK must never run in a browser |\n\n## Verify it landed\n\nInstrumentation isn't done until a session is visible from outside the app:\n\n```bash\nbrizz sessions list --limit 5 --output markdown\n```\n\nor over MCP, `brizz_list_services` then `brizz_search_sessions`. In the dashboard it is\n**Sessions** in the sidebar, filtered to the service — a stale service filter there hides a\nsession that arrived perfectly well.\n\nSpans are batched, so wait 5–10 seconds before believing an empty result.\n\nWhen nothing shows up, work down this list in order:\n\n1. **Credential is in the process** that actually ran, not just your shell. Print it from\n   inside the app if unsure.\n2. **Ordering (Python) or `instrumentModules` (Node).** A Node warning reading\n   *\"Module loaded before instrumentation\"* names this exactly: move `initialize()` to the\n   top of the entry file, and list the library.\n3. **Server-side only.** A browser needs `@brizz/browser`.\n4. **Debug logging** — `BRIZZ_LOG_LEVEL=debug` in Node, the `brizz` logger at `DEBUG` in\n   Python. The SDK then says what it is sending and where.\n5. **401** — an invalid credential, or a proxy stripping the `Authorization` header.\n\nOnly after all five should you suspect the platform.\n\n## Enrichment — what turns spans into analytics\n\nRaw spans give a transcript. User-level views, org rollups, funnels, feedback, and quality\nmetrics need identity and events attached. The pages under `docs/instrument/` cover\nidentifying users and organizations, message IDs, custom events, feedback, and recorded\nmetrics.\n\nAdd each one when the user asks for the analysis that needs it — not all at once up front.\n\n## A service that is already instrumented but sparse\n\nTelemetry arriving with no user, no tool spans, or no events is a diagnosable state, not a\nfresh install. Connect over MCP and run the server's `fix-instrumentation` runbook\n(`brizz_get_skill`), which reads the Telemetry Health Center and names the specific gap.\nCome back here to make the code change it identifies.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}