monitoring-patterns
Skill2 starsChanged 7 days agoMITView on GitHub
Application monitoring patterns covering Prometheus metrics (Counter, Gauge, Histogram, Summary), the prometheus-client Python library, metric naming conventions, labels, and health check endpoints. Use whenever a Python project instruments metrics, uses prometheus-client, or the user asks about Prometheus, metrics, monitoring, health checks, or observability, even if "Prometheus" is not mentioned by name.
In this repository37 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- auditSkill
- backup-patternsSkill
- bash-patternsSkill
- depsSkill
- django-patternsSkill
- docker-patternsSkill
- drf-patternsSkill
- engineering-fundamentalsSkill
- fastapi-patternsSkill
- git-patternsSkill
- go-patternsSkill
- graphql-patternsSkill
- investigateSkill
- javascript-patternsSkill
- logging-patternsSkill
- referenceSkill
- metaSkill
- next-app-router-patternsSkill
- nuxt-patternsSkill
- opentofu-patternsSkill
- prSkill
- python-patternsSkill
- react-patternsSkill
- report-formatSkill
- security-patternsSkill
- slop-patternsSkill
- storybook-patternsSkill
- tailwind-patternsSkill
- test-patternsSkill
- typescript-patternsSkill
- unslopSkill
- vps-provisioningSkill
- vue-patternsSkill
- wcag-auditSkill
- writeSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Default to Histogram over Summary.
- Very specific: line 34
Always set namespace=: unprefixed names collide across apps in a shared Prometheus
- Very specific: line 59
Use a Gauge for queue depth, active sessions, or any value that can drop.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Monitoring Patterns
Review checklist for Prometheus instrumentation. Constructor signatures are in the prometheus-client docs; this file is the naming rules, the cardinality trap, and what to flag.
Picking a metric type
| Type | Use for | Goes down? |
| Counter | Requests, errors, bytes: totals that only increase | No |
| Gauge | Queue depth, active connections, memory: current state | Yes |
| Histogram | Latency, payload size: distribution matters | No |
| Summary | Avoid; the Python client exposes only count and sum, no quantiles | No |
Default to Histogram over Summary. Review the default buckets (.005 through 10, tuned for HTTP latency) against the operation's real distribution rather than accepting them.
Naming
namespace_subsystem_name_unit, snake_case, base units only.
- Counters end in
_total:myapp_errors_total _secondsnot_milliseconds,_bytesnot_megabytes- Name what is measured, not the measurement:
http_request_duration_seconds, nothttp_request_time - Always set
namespace=: unprefixed names collide across apps in a shared Prometheus
Exposing
- Background worker or CLI with no HTTP server:
start_http_server(8000) - ASGI: mount
make_asgi_app()at/metrics - WSGI: mount
make_wsgi_app()at/metrics
Health endpoints
| Endpoint | Returns 200 when | Used by |
/health/live | Process is running | Kubernetes liveness probe |
/health/ready | Dependencies (DB, cache) are reachable | Kubernetes readiness probe |
Return 503, not 500, when a dependency is down: readiness should fail only when the instance cannot serve traffic.
Anti-patterns
failure: high-cardinality label values Using user IDs, request IDs, or email addresses as label values creates millions of time series, crashes Prometheus, and makes dashboards useless. Labels must have bounded, low cardinality.
failure: Counter used for values that decrease
Use a Gauge for queue depth, active sessions, or any value that can drop. A Counter that decreases corrupts rate() calculations in PromQL.
warning: metric names in milliseconds
Prometheus convention is seconds. _milliseconds metrics are incompatible with standard recording rules and dashboards. Convert to seconds and use _seconds.
warning: no namespace on metrics
Without a namespace prefix, metric names from different apps collide in shared Prometheus instances. Always set namespace="yourapp".
warning: single health endpoint used for both liveness and readiness Combining them means a slow database causes the container to be killed and restarted rather than just pulled from load balancing. Keep them separate.
info: default Histogram buckets accepted without review The defaults suit general HTTP latency. For faster or slower operations, define buckets that match the expected distribution.
References
- https://prometheus.io/docs/concepts/metric_types/
- https://prometheus.github.io/client_python/
- https://prometheus.io/docs/practices/naming/
prometheus-client's API surface is stable but check the GitHub release notes before upgrading across minor versions.
Version notes
Checked: 2026-09-26 against Context7 /prometheus/client_python, https://prometheus.github.io/client_python/instrumenting/summary/, https://prometheus.io/download/
- prometheus-client 0.26.0 (2026-07-24), Prometheus 3.15.0 (2026-09-24): Summary row corrected; the Python client "does not compute quantiles locally".
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.