Observability Specification: [Service or platform name]

Complete observability specification for a service or platform: goals, telemetry signals, naming and semantic conventions, log schema, metrics catalogue, tracing, dashboards, SLIs and SLOs, alert rules, retention, cost, privacy and ownership. Concepts follow OpenTelemetry (signals, resources, attributes, context propagation, sampling). Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

1. Goals and scope
2. Architecture and telemetry pipeline
3. Signal standards
4. Naming and semantic conventions
5. Logs
6. Metrics
7. Traces
8. Dashboards
9. SLIs and SLOs
10. Alerting
11. Privacy and security
12. Retention and cost
13. Ownership and governance
14. Appendices

1. Goals and scope

1.1 Goals

1.2 Operator questions

The signals in this specification must answer these questions without deploying new code:

• Is the service healthy for users right now, and since when has it not been?
• Which endpoint, region, version or customer segment is affected?
• Which downstream dependency is slow or failing?
• What changed just before the problem started (deploys, config, traffic)?
• [Question]

1.3 Scope

2. Architecture and telemetry pipeline

Services emit telemetry with the OpenTelemetry SDK through the OTLP protocol to a local collector, which processes, scrubs and exports it to the storage backends.

3. Signal standards

All three signals carry the same resource attributes (4.2) so that a metric spike can be followed to traces and then to logs.

4. Naming and semantic conventions

4.1 General rules

• Attribute and metric names are lowercase, dot-separated namespaces: http.request.method, db.system.
• Custom attributes use the organisation namespace: [org].[domain].[name], for example acme.order.channel.
• Units follow UCUM-style abbreviations in metric metadata (s, By, {request}), not in the name.
• Durations are recorded in seconds as floating point.
• Never put unbounded values (user IDs, URLs with IDs, error messages) into metric attributes.

4.2 Required resource attributes

4.3 Custom attributes register

5. Logs

5.1 Log schema

5.2 Severity guidelines

5.3 Logging rules

• Log once per failure at the boundary that handles it, not at every layer.
• Do not log request or response bodies by default.
• Sample high-volume INFO logs at the collector when volume exceeds [n] lines per second per service.

6. Metrics

6.1 Method

• RED for request-driven components: Rate, Errors, Duration.
• USE for resources: Utilisation, Saturation, Errors.

6.2 Metrics catalogue

6.3 Histogram buckets

[Define standard bucket boundaries or use exponential histograms. Example: latency buckets 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10 seconds.]

6.4 Cardinality budget

The number of time series per metric is the product of distinct values of its attributes:

Example: 5 methods x 40 routes x 12 status codes x 11 buckets x 30 pods gives about 792,000 series. Remove the pod attribute from histograms and aggregate at the collector to bring it under the budget of [n] series per service.

7. Traces

7.1 Instrumentation

7.2 Context propagation

[State the propagation format and where it is applied. Example: "W3C Trace Context (traceparent, tracestate) on all HTTP and gRPC calls; W3C Baggage only for acme.tenant.tier; trace context copied into message headers for queues; batch jobs start a new trace and link to the triggering trace."]

The sequence below shows propagation across a synchronous call and an asynchronous queue.

7.3 Sampling

Effective sampled volume:

where $p_{\text{tail}}$ is the share of unsampled traces kept by tail rules.

8. Dashboards

Dashboards are stored as code in [repository path] and reviewed like any other change.

9. SLIs and SLOs

Burn rate, used by alerts in section 10:

A burn rate of 14.4 sustained for one hour consumes 2% of a 30-day budget.

10. Alerting

10.1 Severity levels

10.2 Alert rules

10.3 Alert hygiene

• Review alert volume monthly; any alert that fired without action is tuned or removed.
• Silence windows require an owner and expiry.
• Target: fewer than [2] pages per on-call shift on average.

11. Privacy and security

Data subject requests: [describe how telemetry is handled for deletion requests, for example "retention below 30 days for logs containing pseudonymous IDs, so data expires within the response deadline"].

12. Retention and cost

Monthly cost estimate per signal:

Cost controls: [list sampling, log level defaults, attribute limits and budget alerts that keep spend within OG-03].

13. Ownership and governance

Changes to this specification follow [process, for example "pull request to the observability repository with review from two guild members"]. A new service is production-ready only when it passes the checklist in appendix 14.1.

14. Appendices

14.1 Service onboarding checklist

• Resource attributes in 4.2 set and verified in each backend.
• RED metrics exported for every entry point.
• Trace context propagated on all inbound and outbound calls.
• Logs follow schema 5.1 and include trace_id.
• Service overview dashboard created from the standard template.
• At least one SLO defined and burn-rate alerts configured with runbooks.
• Privacy rules in section 11 verified by a sample review.

14.2 Glossary

14.3 References

Standard and licence note

Based on OpenTelemetry concepts (signals, resources, semantic conventions, context propagation and sampling) and on common SRE practice for RED and USE metrics and burn-rate alerting. Attribute names shown follow the public OpenTelemetry semantic conventions; check the current version for changes. This template is original text written for this collection and reproduces no text from the specification. Template licence: MIT.