my-notes-viewer/.agents/skills/monitoring-and-performance/SKILL.md

name, description

name	description
monitoring-and-performance	Configure and verify observability for tibi website projects. Covers OpenAPI exposure, Prometheus metrics, Sentry wiring, health/reachability checks, and the operator-facing validation that should exist before a project is considered production-ready.

monitoring-and-performance

When to use this skill

Use this skill when:

• a project needs operator-facing visibility beyond “the page loads”
• you need OpenAPI output for integrations or documentation
• you need Prometheus/Grafana visibility
• you need Sentry or similar error visibility in frontend or server flows
• you want to define the minimum health and observability checks for deploys

Goal

Give later agents a concrete workflow for deciding what should be observable, how it is exposed, and how to verify that exposure.

This skill is not about arbitrary performance tuning. It is about making the running system inspectable enough that operators and developers can see whether it is healthy.

Source of truth

Use these sources when implementing or reviewing observability:

• tibi-server/docs/13-openapi-metrics.md
• tibi-server/docs/02-configuration.md
• .agents/skills/deployment/SKILL.md
• frontend/src/config.ts
• relevant deploy scripts and env/config files

OpenAPI exposure

Tibi-server generates an OpenAPI spec per project:

GET /api/v1/{namespace}/openapi

Use this when:

• a project exposes public API surfaces that need documentation
• integrations or client generators benefit from a machine-readable contract

Collection-level OpenAPI customization lives in collection metadata via meta.openapi.

Use that metadata deliberately to:

• hide endpoints that should not appear in the spec
• add summaries and descriptions
• keep the public API contract readable

Metrics exposure

Prometheus metrics are exposed at:

GET /metrics

Key upstream metric documented today:

• tibi_request_duration_seconds

This is useful for:

• request latency visibility
• collection-level timing comparisons
• basic traffic and error observation in Grafana/Prometheus

Do not enable metrics-like operator expectations in a project and then forget to verify the endpoint actually works in the target environment.

Sentry and error visibility

This stack can surface errors through Sentry-related configuration.

Relevant surfaces include:

• server-level sentry config in tibi-server
• frontend runtime wiring in frontend/src/config.ts
• deploy-time release/build metadata injection where the project uses it

Use Sentry deliberately:

• define DSN, environment, and release expectations
• know whether tracing is wanted or only error capture
• make sure deploy scripts and build metadata agree with the runtime setup

Do not leave a half-configured Sentry setup that looks present but produces unusable traces.

Health and reachability checks

At minimum, operators should be able to verify:

• website URL responds
• admin URL responds
• API responds
• OpenAPI and metrics endpoints respond when they are intended to be used

In this repo family, simple reachability probes are often the first useful health signal. For project delivery, these checks belong next to deploy and sign-off work, not only in ad-hoc troubleshooting.

Recommended patterns

Public API projects

Recommended shape:

• expose OpenAPI intentionally
• add meta.openapi summaries for meaningful endpoints
• verify the spec against the current collection model

Operated production projects

Recommended shape:

• metrics endpoint reachable in the target environment
• at least one documented Grafana/Prometheus use case for request timing
• explicit decision whether Sentry is used or intentionally not used

Basic website deployments

Recommended shape:

• website/admin/API reachability checks are part of deploy verification
• observability is documented enough that later operators know what exists

Anti-patterns

• treating observability as optional once the build passes
• exposing OpenAPI or metrics accidentally without deciding who uses them
• half-configured Sentry with no useful environment or release handling
• relying on manual browser clicks as the only production health check

Verification checklist

After observability-related work, verify all of these:

1. intended OpenAPI exposure works and reflects the current collection config
2. intended metrics exposure works in the target environment
3. Sentry/error visibility is either intentionally configured or intentionally absent
4. deploy-time reachability checks cover website, admin, and API
5. yarn build, yarn build:server, and yarn validate still pass when observability wiring touched frontend/server config

What an LLM should inspect first

When asked to set up monitoring or observability on this starter, inspect in this order:

1. tibi-server/docs/13-openapi-metrics.md
2. tibi-server/docs/02-configuration.md
3. deploy scripts and env/config files
4. frontend/src/config.ts
5. whether the project truly needs OpenAPI, metrics, Sentry, or only reachability checks

This prevents over-documenting features that are not actually wired and under-documenting the ones that matter operationally.