When implementing observability features (logs, metrics, traces), use consistent semantic conventions to ensure data can be correlated and analyzed efficiently across the entire system.
When implementing observability features (logs, metrics, traces), use consistent semantic conventions to ensure data can be correlated and analyzed efficiently across the entire system.
Define core observability attributes in foundational packages that can be imported by other components. This creates a single source of truth for naming conventions.
Use semantic conventions for all observability signals including logs, metrics, and traces:
// Instead of manually adding attributes with varying names:
reqContext.Logger = reqContext.Logger.New("userId", reqContext.UserID, "orgId", reqContext.OrgID, "uname", reqContext.Login)
// Use standardized attribute helpers:
reqContext.Logger = reqContext.Logger.New(log.Attributes(
o11ysemconv.UserID.LogKV(reqContext.UserID),
o11ysemconv.OrgID.LogKV(reqContext.OrgID),
o11ysemconv.Username.LogKV(reqContext.Login),
))
Create consistent naming conventions for metrics that reflect their purpose rather than implementation details. For example, use remote_alertmanager_syncs_total
instead of remote_secondary_forked_alertmanager_syncs_total
.
Use centralized metrics registration to prevent duplicate registrations:
// Instead of:
prometheus.NewRegistry()
// or
prometheus.DefaultRegisterer
// Use the provided utility:
metrics.ProvideRegisterer()
Following these conventions ensures that observability data remains consistent and queryable across the entire system, making it easier to correlate information during debugging and analysis.
Enter the URL of a public GitHub repository