Semantic Convention

Expanded Definition

A semantic convention is the agreed mapping between a telemetry concept and the attribute names, data types, and units used to record it. In observability, that shared vocabulary lets logs, traces, metrics, and events describe the same activity in a consistent way, even when produced by different libraries, services, or teams. For agent observability, semantic conventions are especially important because an autonomous OpenTelemetry semantic convention can make tool calls, model inputs, workflow steps, and failures searchable across environments without custom parsing. Definitions vary across vendors, but the core purpose is stable: standardise meaning before teams standardise dashboards.

In security operations, semantic conventions support reliable detection engineering, incident triage, and auditability because they reduce ambiguity in telemetry. They are not the same as schema enforcement alone, and they do not guarantee good data quality if instrumentation is incomplete or inconsistent. The most common misapplication is treating a naming pattern as a semantic convention, which occurs when teams align on labels but not on field meaning, unit consistency, or event context.

Examples and Use Cases

Implementing semantic conventions rigorously often introduces governance overhead, requiring organisations to weigh easier correlation against stricter instrumentation discipline.

• A platform team records HTTP span attributes using a common convention so service maps remain comparable across microservices and managed agents.
• A security team standardises authentication-related telemetry so failed logins, token refreshes, and access denials can be queried consistently in a SIEM.
• An AI operations team aligns agent tool-call fields, prompt metadata, and response status under a shared model so OpenTelemetry exports can be reused across observability tools.
• A cloud engineering group adopts a convention for resource identifiers and deployment environment labels to reduce re-instrumentation after service migration.
• An incident response team uses the convention to join traces, logs, and metrics from a single transaction path during post-compromise analysis.

These use cases are strongest when the organisation treats semantic conventions as a design control, not just a documentation exercise. The more autonomous or distributed the system becomes, the more valuable a shared telemetry vocabulary is for analysing behaviour without writing custom parsers for every source.

Why It Matters for Security Teams

Security teams rely on telemetry to detect abuse, reconstruct events, and prove control performance. If semantic conventions are inconsistent, detections become brittle, alert enrichment breaks, and audit evidence loses comparability across systems. That risk is not limited to infrastructure monitoring. In agentic AI environments, inconsistent naming for tool calls, model outputs, and execution context can hide risky behaviour such as unexpected delegation, prompt injection effects, or unauthorised state changes. A shared convention also supports stronger governance under the NIST Cybersecurity Framework 2.0 by improving visibility, analysis, and response consistency.

For identity-heavy systems, semantic conventions matter because authentication, session, and entitlement events need stable labels before they can be correlated with identity assurance and access decisions. They also reduce the operational burden of retrofitting telemetry after a security review or control gap. Organisations typically encounter the cost of poor semantic conventions only after an investigation stalls on mismatched fields, at which point standardisation becomes operationally unavoidable to address.

Related resources from NHI Mgmt Group

• What is the difference between SAST and semantic AI code analysis?
• What do organisations get wrong about semantic models in AI governance?
• Why do semantic models matter for agentic AI governance?
• Semantic Chunking