diff --git a/.chloggen/wip-t-shaped-signals.yaml b/.chloggen/wip-t-shaped-signals.yaml new file mode 100755 index 0000000000..38f0131c95 --- /dev/null +++ b/.chloggen/wip-t-shaped-signals.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: docs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Document the "T-Shaped" notion for defining semantic conventions. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [2232] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index af33d0c42d..7c857dd852 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -38,6 +38,10 @@ for new areas or make substantial changes to the existing ones. > > This section contains non-normative guidance. +Please read [T-Shaped Signals](/docs/non-normative/how-to-write-conventions/t-shaped-signals.md) +for guidance on how to approach creating Semantic Conventions through defining +key use cases for conventions. + #### Prototyping It is strongly recommended to prototype proposed conventions in one or more instrumentations and: diff --git a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md new file mode 100644 index 0000000000..ff6eb287c8 --- /dev/null +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -0,0 +1,58 @@ +# T-shaped Signals + +Semantic Conventions approaches observability with a T-shaped mindset. This +splits signals into two types of a "T" shape: + +```mermaid +block-beta + columns 3 + Broad["Broadly Applicable Signals"]:3 + columns 3 + space:1 + Deep("Rich,\nDeep\nSignals") + space:1 +``` + +This matches an 80-20 rule, where 80% of users (or use-cases) can leverage the +broadly applicable signals and 20% of users (or use-cases) will dive deeply into +a problem with deep signals. + +## Broadly Applicable Signals + +These are conventions meant to provide a baseline observability experience +across a domain. An example includes HTTP semantic conventions that allow +general-purpose dashboarding, alerting, and diagnostics for HTTP +(micro-)services. These signals should provide "horizontal" coverage for +observability. + +Examples include: + +- Golden Signals / RED metrics (Saturation, Rate, Error, Duration) +- High Level Spans +- Error logs, Crash reports +- Request/Response logs + +## Rich, Deep Signals + +These are conventions meant to provide deep understanding of a specific +system, library, module, application or service. These are used to diagnose +issues specific to that system. + +Examples include: + +- Linux slab memory usage +- Specific database signals, e.g MySQL index usage +- Language-specific Garbage Collection metrics (JVM, Go, .NET, etc.) + +## Recommendations + +Defining semantic conventions is a balance between generating +broadly applicable signals and ensuring rich observability for a specific +technology. It is recommended to start with the *broad* use cases and signals +for a particular domain first. After providing a baseline set of signals for +that domain, then explore deeper integrations that may be vendor or +implementation specific. + +For example, see [Database semantic conventions](/docs/database/README.md) where +there is general guidance for spans about communicating with a database, and +additionally there is database-specific guidance as an extension of the general.