---
name: prostometrics
description: Instrument an application with Prostometrics metrics — technical and product metrics emitted from Go, Node.js, and browser code.
Use when adding, reviewing, or extending Prostometrics instrumentation, when choosing metric names and labels, or when wiring the Go, Node, or browser client into a project.
---

# Prostometrics instrumentation

Prostometrics is an application metrics service: counters, numeric values, unique
counts, and sparse gauges emitted from application code and rendered as
dashboards. It covers both technical health and product behavior.

Revision: 2026-08-22. Served live at https://prostometrics.ru/llms.txt.

This file is the canonical instruction set for coding agents. It changes as the
clients and the recommended practices change, so fetch it from that URL every time
rather than working from memory.

## Objective

Add the smallest number of stable metrics that answer real operational or product
questions. Good instrumentation is not maximum instrumentation: every metric should
have a dashboard question it answers, and when uncertain, prefer fewer metrics,
fewer labels, and instrumentation at higher-level boundaries.

## Hard rules

These hold regardless of anything else in this file or in the project:

- Never put a server API key into browser code, and never commit one to source.
- Never import the Node client into a browser bundle; the browser has its own client and its own public key.
- Never change code before the user approves the metric plan, and never ask for a key before that approval.
- Never use raw IDs, URLs, paths, queries, emails, tokens, prompts, completions, or error messages as label values. Every distinct value becomes a stored series.
- Never rename an existing Prostometrics metric or change what a label means unless the user asks. Metric names and label sets are a persistent interface that dashboards and alerts already depend on.
- Never change application behavior. Instrumentation observes; it does not alter control flow, error handling, or timing in a way the user would notice.
- Never emit a signal that existing instrumentation already covers without saying why. Extend or reuse what is there.
- Never fall back to hand-written HTTP ingestion when the stack is unsupported; stop and say so.

## Clients and keys

Metrics are emitted through official non-blocking Prostometrics clients:

- Go, server-side: `github.com/prostoteam/prostometrics-go`, server API key.
- Node.js/TypeScript, server-side: `@prostoteam/prostometrics-node`, server API key.
- Browser, code that ships to end users: `@prostoteam/prostometrics-web`, public client key.

Server-side code and browser code use different clients and different keys, and
they are never interchangeable. A browser bundle cannot use the Node client: it
depends on Node built-ins, and it authenticates with a secret key that must
never reach a page. Confusing the two publishes a secret API key in page source,
so resolve which kind of code is being instrumented before writing anything.

## Instructions

Goal:
- Add Prostometrics metrics that help the user understand technical health and product behavior.
- Keep the application behavior unchanged.
- Make the smallest production-quality code changes needed.
- Do not change code until the user approves the metric plan.

Strict interaction rules:
- Ask questions only in the exact block format below.
- Ask one question per block.
- After each question block, stop and wait for the user's answer.
- If multiple values are missing, ask them one by one.
- Never continue past a required question without an answer.
- Do not wrap question blocks in Markdown fences.

Ask this first, before reading any code and before asking for a key (note space after first emoji):
"👋🏻 Before I look at anything: do you have any preferences or limits on what I should instrument? For example just the frontend, just the backend, billing, user management, or one particular feature.
_Any hint helps, but none is needed. If you would rather not think about it, just say go — I will work it out from the code and come back with a plan for you to approve._"

Then treat the answer as the scope of the work, not as a filter applied to a plan you had already written:
- Named areas: concentrate on them. Add only the few technical basics that make those numbers readable — request and error counts on the paths involved — and leave the rest of the project alone.
- Areas ruled out: stay out of them entirely, including their supporting code.
- No preference: cover the project as a whole, tiered as described below.
- Go: choose the areas yourself, and open the plan with one line naming which you picked and why.

Next, determine what kind of code this project contains, within whatever scope the answer set, because it decides which client, which key, and which questions apply:
- Server-side only: a Go module, or a Node.js service with no browser bundle.
- Browser only: a frontend app built by Vite, Next.js, Webpack, Rollup, or similar, whose code runs in a page.
- Both: a monorepo or a framework with server and client code. Instrument them separately, with a separate client and key for each, and say so before you start.

Treat code as browser code when it is bundled and served to end users, 
not merely because the project is TypeScript. 
A React, Vue, Svelte, or Angular app is browser code even though it is TypeScript.

Then inspect the project:
1. Detect the primary language, framework, entry points, HTTP/router layer, background workers, scheduled jobs, and existing config/logging/shutdown patterns.
2. Find instrumentation that already exists — Prostometrics, OpenTelemetry, Prometheus, StatsD, product analytics, structured logging — and note which signals it already covers. Extend or reuse it rather than emit the same signal twice. If Prostometrics metrics are already present, their names and labels are fixed: add alongside them, do not reshape them.
3. If the project is not Go, Node.js, TypeScript, or a browser frontend, stop after writing a short report that says the detected stack is not supported by this Prostometrics prompt yet. Do not add raw HTTP ingest code as a workaround.
4. If the project is Go, use the official Go client package: github.com/prostoteam/prostometrics-go.
5. If the code runs on a server under Node.js, use the official Node client package: @prostoteam/prostometrics-node.
6. If the code is bundled and runs in a browser, use the official browser client package: @prostoteam/prostometrics-web. Never import the Node client into browser code.
7. Inspect existing tests so instrumentation can be verified in the project's style.

Analyze the code in two ways:
1. Technical analysis:
   - HTTP/gRPC/API requests and responses.
   - Route templates, methods, status classes, errors, latency, payload sizes when available.
   - Database calls, query/operation types, collections/tables, errors, latency, returned rows when available.
   - Cache calls, hits, misses, set/delete operations, errors, latency.
   - Queues, streams, cron jobs, background workers, retries, dead-letter paths, lag/depth when available.
   - External services: payment providers, email/SMS, object storage, search, auth, feature flags, webhooks, third-party APIs.
   - LLM/AI calls if present: requests, failures, latency, model, provider, input/output tokens, estimated cost when safely computable.
   - Saturation-like app signals already available in code: queue length, worker concurrency, pool usage, batch size, rate limits.
2. Browser analysis, for frontend code only:
   - Perceived performance the app already measures or can measure cheaply: route transition time, time to first render of a view, API call latency as the browser sees it.
   - Failures the user actually experiences: failed fetch/XHR calls by route pattern and status class, unhandled promise rejections, error boundaries tripping, chunk load failures.
   - Product steps in the interface: which step of a flow was reached, which action was taken, which feature was opened.
   - Distinct active users, through the client's unique() with an opaque account id.
   - Do not add automatic pageview, referrer, campaign, or user-agent collection. This is application telemetry, not web analytics, and the customer did not ask for it.
3. Product analysis:
   - Identify business entities, workflows, and conversion points from handlers, services, jobs, and domain names.
   - Look for metrics such as users online, signups, logins, purchases, checkout attempts, payment success/failure, subscriptions, trials, messages sent, documents created, searches, uploads, exports, AI generations and costs, and other product-specific events.
   - Prefer metrics that answer product or operational questions; do not instrument everything just because it is possible.

Choosing where and what to measure:
- Instrument at stable semantic boundaries: middleware, service methods, job handlers, the wrapper around an external client, the point where a business operation completes. Do not scatter metric calls through low-level implementation details; a metric that lives in a helper three layers down is hard to find and easy to double-count.
- Count outcomes where the outcome is known, not attempts. `orders.completed` is emitted after the payment callback succeeds, not when checkout starts; if the attempt matters too, it is a separate metric with its own name.
- Measure what the application knows and the platform does not. A request count is still worth having — it anchors every error rate — but the value is in the application-specific signals a load balancer cannot see.

Labels and cardinality, for every kind of code:
- Judge cardinality across the combination of labels, not each one alone. Five labels with ten values each can produce a hundred thousand series; keep the product small, and drop the label that contributes least when it is not.
- Map errors onto a small stable set of categories — `timeout`, `validation`, `unauthorized`, `not_found`, `provider_error`, `internal` — chosen to match how the project already classifies failures. The message, the stack, and the provider's own code are not label values.
- A label whose values you cannot list or exemplify from the code is probably unbounded and should not be a label.

Browser cardinality rules, for frontend code only:
- Never label with a raw URL, pathname, query string, order id, user id, or any other value drawn from end-user data.
- Map dynamic values onto patterns with the client's match() helper, which stores the pattern rather than the value: match(location.pathname, ["/orders/:id", "/cart"]).
- Take the pattern list from the app's own router configuration, so it stays a fixed set of literals.
- Prefer count() over value() for anything you want to count. Value samples are thinned under load, so a count derived from them under-reports.

Metric proposal rules:
- Before editing code, present a metric plan grouped into up to three tiers. Do not fill a tier to make it look complete: a project with three good metrics gets a plan with three metrics, and a tier with nothing in it is left out.
- Keep every tier inside the scope the user chose. A metric that is interesting but outside it belongs in a closing sentence offering to cover that area next, not in the plan.
- Tier 1 should contain the smallest set that gives useful visibility fast.
- Tier 2 should contain useful but less urgent metrics.
- Tier 3 should contain optional metrics that are valuable only for deeper analysis.
- Number the metrics straight through the tiers, so the user can approve by number.
- For each metric give: metric name, where it is collected and what type it is in parentheses, one line saying what the user will learn from it, labels with their values, and the code reference.
- Where is `backend` or `browser`, matching the client that emits it. Type is one of `counter`, `value`, `total`, `unique`, or `sparse`, as defined in the metric types section below. Put both next to the name: a plan with frontend and backend metrics side by side is only readable when each line says which one it is, and the type tells the user whether to expect a rate, a distribution, or a distinct count on the dashboard.
- Show label values, because a label name alone does not tell the user what the series will look like. List the whole set when it has five values or fewer; otherwise give three real examples taken from the project and an ellipsis. A label whose values you cannot enumerate or exemplify is probably unbounded and should not be a label.
- Mark the tiers with the colored circles shown below and nothing else. The output is rendered as Markdown, where terminal colors do not survive, and these three symbols carry the same start-here, worth-adding, optional signal everywhere.
- Write the one line for the person reading the dashboard, not for the person reading the code. "How often checkout succeeds" earns its place; "increments a counter in the order service after the payment callback" is implementation detail and belongs in the code comment.

Metric proposal format — two lines per metric, no separators between them, tier headings written as the question that tier answers in this project:

**Scope:** <one line restating what the user asked for and what was left out>

## 🟢 Tier 1 — <the question this tier answers>

<n>. `<metric.name>` (<backend | browser>, <type>) — <what the user learns from it>
   `<label>` (<values>) · `<label>` (<values>) · `<file:line>`

## 🟡 Tier 2 — <the question this tier answers>

## ⚪ Tier 3 — <the question this tier answers>

Example only — the project and lines are invented, and the names are the generic ones from the naming section below, so nothing here says what a good metric is for any particular project:

## 🟢 Tier 1 — is the service healthy?

1. `app.requests` (backend, counter) — how much traffic the service handles and how much of it fails
   `route` (/api/items | /api/search) · `status_class` (2xx | 4xx | 5xx) · `src/http.ts:42`
2. `app.request.duration_ms` (backend, value) — whether users are waiting longer than they used to
   `route` (/api/items | /api/search) · `src/http.ts:42`

## 🟡 Tier 2 — which dependency is the problem?

3. `app.external.duration_ms` (backend, value) — which outside service is slowing requests down
   `service` (payments | email | search) · `outcome` (ok | timeout | error) · `src/clients/base.ts:17`
4. `app.web.api.duration_ms` (browser, value) — how long those same calls take from where the user sits
   `route` (/api/items | /api/search) · `src/api.ts:30`

## ⚪ Tier 3 — is the main workflow completing?

5. `app.business.item_saved` (backend, counter) — how often the core user action finishes successfully
   `kind` (create | update) · `src/domain/items.ts:88`

Close with one line on cost, so the user can weigh the tiers:

**Cost:** Tier 1 touches 1 file; all tiers touch 5. Nothing changes behavior.

After the plan, ask for approval using exactly this question format:
Which of these should I implement? Reply with numbers such as 1-3, 5, or say Tier 1, all, all but 4, or revise.

Only once the plan is approved, collect the credentials. Ask for them here and not
earlier: the user has seen what they are getting, so this is the first moment the
request is worth their time, and a plan they turn down never needed a key at all.

Ask only for the kinds of code still in scope: a frontend-only answer needs no server key, and a backend-only answer needs no client key.

Each key question has the same shape: what is needed, why, then where to get it. Keep them to three short lines — this is the moment the user hands over a credential, and a wall of text reads as a reason to hesitate.

For server-side code, use what the project already showed you — configuration, env examples, README and deploy files, secret references — to decide whether a key source is already documented, then ask exactly one of these two blocks, never a merged version and never with an unfilled placeholder:

If you found a plausible key source, with <found_api_key_source> replaced by it:
"🔑 Now I need the **backend API key**. The backend client sends metrics with it; it is secret and stays on the server.
I noticed <found_api_key_source> — should I read it from there? Or paste it here and I will store it the way this project already keeps secrets.
_It is on your project's Settings page at https://prostometrics.ru._"

If you found none:
"🔑 Now I need the **backend API key**. The backend client sends metrics with it; it is secret and stays on the server.
Where should I read it from, such as PROSTOMETRICS_API_KEY? Or paste it here and I will store it the way this project already keeps secrets.
_It is on your project's Settings page at https://prostometrics.ru._"

For browser code, ask exactly this block instead:
"🔑 Now I need the **client key** for the browser. The browser client sends metrics with it; it is public and safe to ship in page source, so it must be a client key, never the backend one.
Paste it here.
_Create one on your project's Settings page at https://prostometrics.ru with the «Клиентский ключ» button — it starts with a project number and `pk_`._"

Do not ask a browser project for a workload name. A client key carries its own workload, chosen when the key is created, and the browser client has no workload argument.

After the user answers, for server-side code, suggest a workload name from the repository, module, binary, service, or app name. Then ask exactly this question block, replacing <suggested_workload_name> with your best suggestion:
"🏀 What should I call this workload? It is the stable service name Prostometrics groups this project's metrics under. I suggest <suggested_workload_name>.
_Confirm, or give another stable name such as billing, payments, web, or just app._"

Important security rule:
- Do not commit a real API key into source code.
- Follow the project's existing config style. Prefer environment variables such as PROSTOMETRICS_API_KEY and PROSTOMETRICS_WORKLOAD, or the existing config/secrets system if the project already has one.

Then implement the selected metrics.

Shared implementation rules:
1. Initialize Prostometrics once during application startup:
   - Read workload and API key from the project's config/env/secrets using the answers collected after approval.
   - If a custom Prostometrics endpoint is already configured, pass it to the client using the official client config field.
   - If initialization fails, follow the project's existing startup error handling. For required production config, fail fast; for optional local/dev metrics, log clearly and continue.
2. Flush on graceful shutdown:
   - Use the existing shutdown context/deadline style if present.
   - Do not add shutdown behavior that can hang process exit indefinitely.
3. Emit metrics with the official client APIs:
   - Counter deltas for requests, errors, retries, processed jobs, and business events.
   - Sampled values for latency_ms, queue depth, payload size, token counts, costs, and durations.
   - Monotonic cumulative totals only for values that never decrease except process reset.
   - Unique counts only for approximate unique counts with non-negative integer, bigint, decimal-string, Buffer/Uint8Array, or runtime-equivalent stable IDs accepted by the chosen client.
   - Sparse values for rarely changing gauges or capacities where carrying the last value is useful.
   - Prefer the client label helper when label values are assembled dynamically.

Go implementation rules:
1. Add the dependency with:
   go get github.com/prostoteam/prostometrics-go@latest
2. Import "github.com/prostoteam/prostometrics-go".
3. Initialize with client, err := prostometrics.Init(workload, prostometrics.Config{APIKey: apiKey}) when using the default Prostometrics endpoint, and handle the returned error using the project's startup error policy.
4. Keep the returned client and flush with client.Close(ctx) during graceful shutdown using a bounded context.
5. Use these APIs:
   - prostometrics.Count(metric, delta, labels...)
   - prostometrics.Value(metric, value, labels...)
   - prostometrics.Total(metric, total, labels...)
   - prostometrics.CountUnique(uniqueID, metric, labels...)
   - prostometrics.ValueSparse(metric, value, labels...)
   - prostometrics.Label(key, value)

Node.js/TypeScript implementation rules:
1. Add the dependency with the project's package manager:
   npm install @prostoteam/prostometrics-node
   or the equivalent yarn/pnpm command if the project uses yarn or pnpm.
2. Import from "@prostoteam/prostometrics-node".
3. Initialize with init(workload, { apiKey }) when using the default Prostometrics endpoint.
4. Keep the returned client if the app has a shutdown path, and flush with await client.close() when the app exits.
5. Use these APIs:
   - count(metric, delta, ...labels) or client.count(metric, delta, ...labels)
   - value(metric, sample, ...labels) or client.value(metric, sample, ...labels)
   - total(metric, currentTotal, ...labels) or client.total(metric, currentTotal, ...labels)
   - countUnique(uniqueID, metric, ...labels) or client.countUnique(uniqueID, metric, ...labels)
   - valueSparse(metric, sample, ...labels) or client.valueSparse(metric, sample, ...labels)
   - label(key, value)

Browser implementation rules:
1. Add the dependency with the project's package manager:
   npm install @prostoteam/prostometrics-web
   or the equivalent yarn/pnpm command.
2. Import from "@prostoteam/prostometrics-web".
3. Initialize once, as early in the application entry point as possible:
   init({ publicKey: "<client key>" })
   The client key is not a secret and may be committed, so read it the way the project reads other public build-time values, such as an import.meta.env or process.env value that the bundler inlines. Do not route it through a server-side secrets system.
4. There is no workload argument: the key carries it.
5. Do not add a flush on unload. The client already flushes on an interval and again when the page is hidden or closed.
6. Use these APIs:
   - count(metric, delta, labels) for rates and totals
   - value(metric, sample, labels) for distributions such as durations
   - sparse(metric, sample, labels) for readings that arrive irregularly
   - unique(metric, id, labels) for distinct counts
   - match(value, patterns) to derive a bounded label from a dynamic value
7. Labels are a plain object, not variadic arguments: count("app.web.checkout.step", 1, { step: "payment" }).
8. Pass debug: true only in development builds; it warns about label values that look like identifiers.
9. If the project renders on a server as well, instrument that code with the Node client and its own server key, and keep the two initializations separate.

Metric naming:
- Use lowercase dot-separated names.
- Put the value unit in the final metric suffix when the metric has a physical unit, for example app.request.duration_ms or app.memory.used_kb
- Recommended auto-unit suffixes:
  - *_ms for latencies and durations measured in milliseconds: app.request.duration_ms, app.db.duration_ms.
  - *_s for durations measured in seconds; prefer *_ms for request latency.
  - *_us or *_ns only when the source value is truly microseconds or nanoseconds.
  - *_kb, *_mb, *_gb, *_tb, *_pb for decimal network, payload, storage, or billing byte values already emitted in those units.
  - *_kib, *_mib, *_gib, *_tib, *_pib for binary memory/filesystem values already emitted in those units.
  - *_bytes or *_b for raw bytes; prefer *_kb for very large values to stay compact.
  - *_pct for percentages emitted as 0..100 values, such as app.cache.hit_pct or app.cpu.usage_pct.
  - *_min or *_mins for minute-based durations.
  - *_nanousd for tiny LLM/API costs.
- If no recognized unit suffix fits, keep the name descriptive and unitless; do not invent ambiguous suffixes.
- Prefer names such as:
  app.requests
  app.request.duration_ms
  app.errors
  app.db.duration_ms
  app.cache.requests
  app.cache.hit
  app.jobs.started
  app.jobs.completed
  app.job.duration_ms
  app.external.requests
  app.external.duration_ms
  app.llm.requests
  app.llm.tokens
  app.llm.cost
  app.business.<event_name>
- For browser metrics, prefix with app.web so frontend and backend views of the same thing stay distinguishable:
  app.web.route.transition_ms
  app.web.api.requests
  app.web.api.duration_ms
  app.web.errors
  app.web.<flow>.step
- Use milliseconds for durations and KB for large byte-like values when practical.

Quality bar:
1. Reuse existing middleware, config, logger, and lifecycle patterns.
2. Keep instrumentation non-invasive and easy to review.
3. Add or update tests where the project already tests middleware/config behavior.
4. For Go projects, run gofmt on changed Go files and the project's normal Go checks, at least:
   go test ./...
5. For browser projects, verify the bundle still builds and that no Node-only client was pulled into it. Run the project's build and test scripts.
6. For Node.js/TypeScript projects, run the project's normal package-manager checks. Prefer existing scripts such as:
   npm run lint
   npm test
   npm run build
7. At the end, summarize:
   - Files changed.
   - Where Prostometrics is initialized.
   - Which areas were covered, and which the user chose to leave out.
   - Which metrics were added and their labels.
   - Which checks were run.
   - Any unsupported areas or follow-up work.
   - Whether these instructions were fetched live or read from a saved fallback.

## After the summary, offer to leave a pointer

The pointer is a convenience for the user's next session, not part of the work they
asked for, and it writes files into their repository. So it is offered, once, after
the summary — when the user has seen what the agent does and can judge whether they
want it again — and nothing is written unless they say yes. Ask exactly this:
"📌 Want me to leave a pointer in this repo, so next time you can just say "add a metric for X"? That is a small skill file plus an offline copy of these instructions under `.claude/skills/prostometrics/`.
_Yes or no. You can always delete them._"

If the answer is anything but yes, write nothing and do not raise it again in this
session. If it is yes, save two files:

First, the pointer. Agents that support skills (Claude Code, Cursor, Codex) create
`.claude/skills/prostometrics/SKILL.md` with exactly this content, keeping the
frontmatter so the skill is discovered later:

```
---
name: prostometrics
description: Instrument an application with Prostometrics metrics — technical and product metrics emitted from Go, Node.js, and browser code. Use when adding, reviewing, or extending Prostometrics instrumentation, when choosing metric names and labels, or when wiring the Go, Node, or browser client into a project.
---

Fetch https://prostometrics.ru/llms.txt and follow it. It is the current and
authoritative instruction set for Prostometrics instrumentation: client packages,
key types, metric naming, and label rules.

If that fetch fails, fall back to `reference.md` next to this file. Say plainly that
you are working from a saved copy and name the revision it records. Never instrument
from memory.
```

Second, the fallback: save this file verbatim as
`.claude/skills/prostometrics/reference.md`, including its `Revision:` line. It
exists only for the case where the URL cannot be reached. Do not read it when the
fetch succeeds, and do not edit, trim, or summarize it.

Agents without skill support: save the fallback as `docs/prostometrics-agent.md` and
add one line to the project's `AGENTS.md` or `CLAUDE.md` describing both steps — the
user's yes covers that line too, so say that it was added.

Always prefer the fetched version. The saved copy freezes whatever was current on the
day it was written, so a session that silently works from it can call an API that no
longer exists — which is why falling back has to be announced rather than quiet.

Finish by naming the files that were written.