forked from cms/tibi-svelte-starter
✨ feat: enhance medialib image handling and add asset URL resolution
- Implemented `resolveApiAssetUrl` function to normalize asset URLs based on API base. - Updated `MedialibImage` component to utilize new asset URL resolution and added support for alt text and class properties. - Enhanced image loading behavior with improved width measurement and focal point handling. - Added placeholder image handling and improved accessibility with alt text. - Introduced new test script for auditing broken links in skill documentation. - Expanded seeded test content to include medialib entries and updated related tests for pagebuilder previews. - Improved global setup and teardown logging for clarity on seeded content management.
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: monitoring-and-performance
|
||||
description: 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user