Security Observability Semantic Conventions

This repo is built on top of this otel specification version

Semantic Conventions are metric and attribute names that are defined so that they mean the same thing to all parties producing and consuming the observability data. Raw timeseries and span data are stored in schemaless datastores and thus there is not a strictly defined schema file. This design allows for agents to all be at various levels of support in what they produce for observability while the consumers of the data do the best with what they have.

The single source of truth of semantic convention definitions are the yaml files in the model/ directory. The single source of truth for the semantic convention documentation are the markdown files in the docs/ directory.

The semantic convention definitions are used to fill in table data in the semantic convention documentation. This is the same pattern as opentelemetry's semantic-convention repo. Contrasts Security Observability builds on top of the existing semantic-conventions of opentelemetry and this secobs-semantic-conventions document should be interpreted as an addendum to the core opentelemtry semantic conventions standard.

Model Definition Files

The model definition files have a particular schema associated to them that the opentelemetry semconvgen build tool interprets and processes. semconvgen is used to generate documentation data from the definition files. Specific language agents can use these definition files to generate library code.

Semantic Conventions for Security Observability. The model definitions use a syntax defined at Semantic Convention YAML Language

Releases

Semantic Conventions are versioned and the semantic version used by an agent is encoded as a Resource attribute. The backend will accept multiple semantic versions in use simultaneously by different agent instances.

The Secobs Semantic Conventions version will encompass the version of the addendum here and the core semantic conventions version which is v1.22.0 at the time of this writing.

Consuming the Semantic Convention Documentation

The markdown documentation along with any generated table information from the definition files can be consumed by just pointing a browser to the docs/ directory in this repo.