feat: add OpenTelemetry metrics with Prometheus-compatible export

.env.example

@@ -12,6 +12,10 @@ SERVER_PORT=8080
 # Logging
 LOG_LEVEL=info
 
+# Metrics configuration
+METRICS_ENABLED=true
+METRICS_NAMESPACE=secrets
+
 # Master keys (Envelope Encryption)
 # Generate a new master key using: ./bin/app create-master-key
 # Each key must be exactly 32 bytes (256 bits), base64-encoded

README.md

@@ -13,7 +13,7 @@ Secrets is inspired by **HashiCorp Vault** ❤️, but it is intentionally **muc
 The default way to run Secrets is the published Docker image:
 
 ```bash
-docker pull allisson/secrets:v0.2.0
+docker pull allisson/secrets:v0.3.0
 ```
 
 Use pinned tags for reproducible setups. `latest` is also available for fast iteration.
@@ -27,6 +27,13 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 1. 🐳 **Run with Docker image (recommended)**: [docs/getting-started/docker.md](docs/getting-started/docker.md)
 2. 💻 **Run locally for development**: [docs/getting-started/local-development.md](docs/getting-started/local-development.md)
 
+## 🆕 What's New in v0.3.0
+
+- 📊 OpenTelemetry metrics with Prometheus-compatible export at `GET /metrics`
+- ⚙️ Runtime metrics controls via `METRICS_ENABLED` and `METRICS_NAMESPACE`
+- 📈 HTTP and business-operation metrics for auth, secrets, and transit flows
+- 📘 New monitoring operations guide: [docs/operations/monitoring.md](docs/operations/monitoring.md)
+
 ## 📚 Docs Map
 
 - **Start Here**
@@ -36,14 +43,15 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 - 🧰 **Troubleshooting**: [docs/getting-started/troubleshooting.md](docs/getting-started/troubleshooting.md)
 - ✅ **Smoke test script**: [docs/getting-started/smoke-test.md](docs/getting-started/smoke-test.md)
 - 🧪 **CLI commands reference**: [docs/cli/commands.md](docs/cli/commands.md)
-- 🚀 **v0.2.0 release notes**: [docs/releases/v0.2.0.md](docs/releases/v0.2.0.md)
+- 🚀 **v0.3.0 release notes**: [docs/releases/v0.3.0.md](docs/releases/v0.3.0.md)
 
 - **By Topic**
 - ⚙️ **Environment variables**: [docs/configuration/environment-variables.md](docs/configuration/environment-variables.md)
 - 🏗️ **Architecture concepts**: [docs/concepts/architecture.md](docs/concepts/architecture.md)
 - 🔒 **Security model**: [docs/concepts/security-model.md](docs/concepts/security-model.md)
 - 📘 **Glossary**: [docs/concepts/glossary.md](docs/concepts/glossary.md)
 - 🔑 **Key management operations**: [docs/operations/key-management.md](docs/operations/key-management.md)
+- 📊 **Monitoring and metrics**: [docs/operations/monitoring.md](docs/operations/monitoring.md)
 - 🚑 **Failure playbooks**: [docs/operations/failure-playbooks.md](docs/operations/failure-playbooks.md)
 - 🏭 **Production deployment**: [docs/operations/production.md](docs/operations/production.md)
 - 🛠️ **Development and testing**: [docs/development/testing.md](docs/development/testing.md)
@@ -74,6 +82,7 @@ All detailed guides include practical use cases and copy/paste-ready examples.
 - 👤 Token-based authentication and policy-based authorization
 - 📦 Versioned secrets by path (`/v1/secrets/*path`)
 - 📜 Audit logs with request correlation (`request_id`) and filtering
+- 📊 OpenTelemetry metrics with Prometheus-compatible `/metrics` export
 
 ## 🌐 API Overview
 
@@ -84,6 +93,7 @@ All detailed guides include practical use cases and copy/paste-ready examples.
 - Secrets: `POST/GET/DELETE /v1/secrets/*path`
 - Transit: `POST /v1/transit/keys`, `POST /v1/transit/keys/:name/rotate`, `POST /v1/transit/keys/:name/encrypt`, `POST /v1/transit/keys/:name/decrypt`, `DELETE /v1/transit/keys/:id` ([create vs rotate](docs/api/transit.md#create-vs-rotate), [error matrix](docs/api/transit.md#endpoint-error-matrix))
 - Audit logs: `GET /v1/audit-logs`
+- Metrics: `GET /metrics` (available when `METRICS_ENABLED=true`)
 
 ## 📄 License
 

docs/CHANGELOG.md

@@ -1,6 +1,24 @@
 # 🗒️ Documentation Changelog
 
-> Last updated: 2026-02-14
+> Last updated: 2026-02-16
+
+## 2026-02-16 (docs v5 - documentation quality improvements)
+
+- Added `What's New in v0.3.0` section to root `README.md`
+- Added Prometheus + Grafana quickstart and a metrics naming contract to `docs/operations/monitoring.md`
+- Added production hardening guidance for securing `/metrics` exposure
+- Added feature PR docs consistency checklist to `docs/contributing.md`
+- Added metrics troubleshooting matrix to `docs/getting-started/troubleshooting.md`
+- Added local and Docker command parity examples in `docs/cli/commands.md`
+- Added telemetry breaking vs non-breaking examples in `docs/api/versioning-policy.md`
+
+## 2026-02-16 (docs v4 - v0.3.0 release prep)
+
+- Added release notes page: `docs/releases/v0.3.0.md` and set it as the current release in docs indexes
+- Updated pinned Docker examples from `allisson/secrets:v0.2.0` to `allisson/secrets:v0.3.0`
+- Added monitoring links to root README and expanded API overview with `GET /metrics`
+- Aligned monitoring operations with implementation (`secret_create`, `secret_get_version`, `audit_log_delete`, `transit_key_rotate`)
+- Clarified metrics disable behavior (`METRICS_ENABLED=false` removes metrics middleware and `/metrics` route)
 
 ## 2026-02-14 (docs v3 - v0.2.0 release prep)
 

docs/README.md

@@ -1,6 +1,6 @@
 # 📚 Secrets Documentation
 
-> Last updated: 2026-02-14
+> Last updated: 2026-02-16
 
 Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 
@@ -25,6 +25,7 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 🔒 [concepts/security-model.md](concepts/security-model.md)
 - 📘 [concepts/glossary.md](concepts/glossary.md)
 - 🔑 [operations/key-management.md](operations/key-management.md)
+- 📊 [operations/monitoring.md](operations/monitoring.md)
 - 🏭 [operations/production.md](operations/production.md)
 - 🚑 [operations/failure-playbooks.md](operations/failure-playbooks.md)
 - 🛠️ [development/testing.md](development/testing.md)
@@ -55,12 +56,13 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 
 OpenAPI scope note:
 
-- `openapi.yaml` is a baseline subset for common API flows in `v0.2.0`
+- `openapi.yaml` is a baseline subset for common API flows in `v0.3.0`
 - Full endpoint behavior is documented in the endpoint pages under `docs/api/`
 
 ## 🚀 Releases
 
-- 📦 [releases/v0.2.0.md](releases/v0.2.0.md)
+- 📦 [releases/v0.3.0.md](releases/v0.3.0.md)
+- 📦 [releases/v0.2.0.md](releases/v0.2.0.md) (historical)
 - 📦 [releases/v0.1.0.md](releases/v0.1.0.md) (historical)
 
 ## 🧠 ADRs

docs/api/versioning-policy.md

@@ -1,6 +1,6 @@
 # 🧩 API Compatibility and Versioning Policy
 
-> Last updated: 2026-02-14
+> Last updated: 2026-02-16
 > Applies to: API v1
 
 This page defines compatibility expectations for HTTP API changes.
@@ -11,15 +11,15 @@ This page defines compatibility expectations for HTTP API changes.
 - Existing endpoint paths and JSON field names are treated as stable unless explicitly deprecated
 - OpenAPI source of truth: `docs/openapi.yaml`
 
-## OpenAPI Coverage (v0.2.0)
+## OpenAPI Coverage (v0.3.0)
 
 - `docs/openapi.yaml` is a baseline subset focused on high-traffic/common integration flows
 - Endpoint pages in `docs/api/*.md` define full public behavior for covered operations
 - Endpoints may exist in runtime before they are expanded in OpenAPI detail
 
 ## App Version vs API Version
 
-- Application release `v0.2.0` is pre-1.0 software and may evolve quickly
+- Application release `v0.3.0` is pre-1.0 software and may evolve quickly
 - API v1 path contract (`/v1/*`) remains the compatibility baseline for consumers
 - Breaking API behavior changes require explicit documentation and migration notes
 
@@ -48,6 +48,19 @@ Usually non-breaking:
 - clarifying documentation text and examples
 - adding additional error examples without changing behavior
 
+## Telemetry Change Examples
+
+Breaking telemetry examples:
+
+- renaming a published metric name (for example `secrets_http_requests_total`)
+- renaming/removing metric labels used by dashboards or alerts
+
+Non-breaking telemetry examples:
+
+- adding a new metric family
+- adding new label values for existing labels
+- adding new dashboard examples without changing metric contracts
+
 ## Deprecation Guidance
 
 - Mark deprecated behavior clearly in endpoint docs

docs/cli/commands.md

@@ -1,6 +1,6 @@
 # 🧪 CLI Commands Reference
 
-> Last updated: 2026-02-14
+> Last updated: 2026-02-16
 
 Use the `app` CLI for server runtime, key management, and client lifecycle operations.
 
@@ -12,10 +12,10 @@ Local binary:
 ./bin/app <command> [flags]
 ```
 
-Docker image (v0.2.0):
+Docker image (v0.3.0):
 
 ```bash
-docker run --rm --env-file .env allisson/secrets:v0.2.0 <command> [flags]
+docker run --rm --env-file .env allisson/secrets:v0.3.0 <command> [flags]
 ```
 
 ## Core Runtime
@@ -24,18 +24,34 @@ docker run --rm --env-file .env allisson/secrets:v0.2.0 <command> [flags]
 
 Starts the HTTP API server.
 
+Local:
+
 ```bash
 ./bin/app server
 ```
 
+Docker:
+
+```bash
+docker run --rm --network secrets-net --env-file .env -p 8080:8080 allisson/secrets:v0.3.0 server
+```
+
 ### `migrate`
 
 Runs database migrations.
 
+Local:
+
 ```bash
 ./bin/app migrate
 ```
 
+Docker:
+
+```bash
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.3.0 migrate
+```
+
 ## Key Management
 
 ### `create-master-key`
@@ -46,10 +62,18 @@ Flags:
 
 - `--id`, `-i`: master key ID
 
+Local:
+
 ```bash
 ./bin/app create-master-key --id default
 ```
 
+Docker:
+
+```bash
+docker run --rm allisson/secrets:v0.3.0 create-master-key --id default
+```
+
 ### `create-kek`
 
 Creates an initial KEK from the active master key.
@@ -58,10 +82,18 @@ Flags:
 
 - `--algorithm`, `--alg`: `aes-gcm` (default) or `chacha20-poly1305`
 
+Local:
+
 ```bash
 ./bin/app create-kek --algorithm aes-gcm
 ```
 
+Docker:
+
+```bash
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.3.0 create-kek --algorithm aes-gcm
+```
+
 ### `rotate-kek`
 
 Rotates KEK to a new version.
@@ -70,10 +102,18 @@ Flags:
 
 - `--algorithm`, `--alg`: `aes-gcm` (default) or `chacha20-poly1305`
 
+Local:
+
 ```bash
 ./bin/app rotate-kek --algorithm aes-gcm
 ```
 
+Docker:
+
+```bash
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.3.0 rotate-kek --algorithm aes-gcm
+```
+
 After master key or KEK rotation, restart API server instances so they load updated key material.
 
 ## Client Management
@@ -155,8 +195,9 @@ Examples:
 ./bin/app clean-audit-logs --days 90 --format text
 
 # Docker form
-docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.2.0 \
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.3.0 \
   clean-audit-logs --days 90 --dry-run --format json
+
 ```
 
 Example text output:

docs/configuration/environment-variables.md

@@ -1,6 +1,6 @@
 # ⚙️ Environment Variables
 
-> Last updated: 2026-02-14
+> Last updated: 2026-02-16
 
 Secrets is configured through environment variables.
 
@@ -21,6 +21,9 @@ MASTER_KEYS=default:BASE64_32_BYTE_KEY
 ACTIVE_MASTER_KEY_ID=default
 
 AUTH_TOKEN_EXPIRATION_SECONDS=86400
+
+METRICS_ENABLED=true
+METRICS_NAMESPACE=secrets
 ```
 
 ## Notes
@@ -29,6 +32,9 @@ AUTH_TOKEN_EXPIRATION_SECONDS=86400
 - 📏 Each master key must represent exactly 32 bytes (256 bits)
 - ⭐ `ACTIVE_MASTER_KEY_ID` selects which master key encrypts new KEKs
 - ⏱️ `AUTH_TOKEN_EXPIRATION_SECONDS` defaults to 24h behavior when set to `86400`
+- 📊 `METRICS_ENABLED` enables/disables OpenTelemetry metrics collection (default: `true`)
+- 🏷️ `METRICS_NAMESPACE` sets the prefix for all metric names (default: `secrets`)
+- 📉 When `METRICS_ENABLED=false`, HTTP metrics middleware and the `/metrics` route are disabled
 - 🔄 After changing `MASTER_KEYS` or `ACTIVE_MASTER_KEY_ID`, restart API servers to load new values
 
 ## Master key generation
@@ -45,6 +51,7 @@ docker run --rm allisson/secrets:latest create-master-key --id default
 
 ## See also
 
+- [Monitoring](../operations/monitoring.md)
 - [Docker getting started](../getting-started/docker.md)
 - [Local development](../getting-started/local-development.md)
 - [Production operations](../operations/production.md)

docs/contributing.md

@@ -1,6 +1,6 @@
 # 🤝 Documentation Contributing Guide
 
-> Last updated: 2026-02-14
+> Last updated: 2026-02-16
 
 Use this guide when adding or editing project documentation.
 
@@ -66,6 +66,16 @@ This target runs markdown linting and offline markdown link validation.
 4. Terminology is consistent across files
 5. `docs/CHANGELOG.md` updated for significant documentation changes
 
+## Feature PR Docs Consistency Checklist
+
+For behavior changes, update all relevant docs in the same PR:
+
+1. Environment variables and defaults (`docs/configuration/environment-variables.md`)
+2. API overview and endpoint pages (`README.md`, `docs/api/*.md`)
+3. Operational runbooks (`docs/operations/*.md`)
+4. Release notes (`docs/releases/vX.Y.Z.md`) and `docs/CHANGELOG.md`
+5. Local and Docker examples (`docs/getting-started/*.md`, `docs/cli/commands.md`)
+
 ## Ownership and Review Cadence
 
 - Docs owners: project maintainers and reviewers for touched domain (`api`, `operations`, `security`)