From 44840f7b3e6f6245e9e86c6297bdb48d66b3ac69 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 5 May 2025 14:18:49 -0400 Subject: [PATCH 01/15] Attempt a write-up about t-shaped-signals. --- docs/non-normative/t-shaped-signals.md | 45 ++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/non-normative/t-shaped-signals.md diff --git a/docs/non-normative/t-shaped-signals.md b/docs/non-normative/t-shaped-signals.md new file mode 100644 index 0000000000..51bef96eef --- /dev/null +++ b/docs/non-normative/t-shaped-signals.md @@ -0,0 +1,45 @@ +# 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 +boardly applicable signals and 20% of users (or use-cases) will dive deep 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.) \ No newline at end of file From c5f0cb767eb656175cdbb3426b1db69630faa015 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 1 Jul 2025 08:17:50 -0400 Subject: [PATCH 02/15] Move guidance into how-to-write section. --- .../{ => how-to-write-conventions}/t-shaped-signals.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/non-normative/{ => how-to-write-conventions}/t-shaped-signals.md (100%) diff --git a/docs/non-normative/t-shaped-signals.md b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md similarity index 100% rename from docs/non-normative/t-shaped-signals.md rename to docs/non-normative/how-to-write-conventions/t-shaped-signals.md From b30e68ea0ea810326d233893321fd895883be8d8 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 1 Jul 2025 09:40:03 -0400 Subject: [PATCH 03/15] Add changelog. --- .chloggen/wip-t-shaped-signals.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100755 .chloggen/wip-t-shaped-signals.yaml diff --git a/.chloggen/wip-t-shaped-signals.yaml b/.chloggen/wip-t-shaped-signals.yaml new file mode 100755 index 0000000000..7fee255ec4 --- /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: other + +# 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: From ea421cf53f49a679701a50b6f9cef4e555eec228 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 1 Jul 2025 09:46:06 -0400 Subject: [PATCH 04/15] Add recommendations. --- .../how-to-write-conventions/t-shaped-signals.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) 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 index 51bef96eef..08f7f4d428 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -42,4 +42,11 @@ Examples include: - Linux slab memory usage - Specific database signals, e.g MySQL index usage -- Language-specific Garbage Collection metrics (JVM, Go, .NET, etc.) \ No newline at end of file +- Language-specific Garbage Collection metrics (JVM, Go, .NET, etc.) + +## Recommendations + +While defining semantic conventions can be a balance between geneating +broadly applicable signals and defining deep at the same time, it is recommended +to start with the *broad* use cases and signals for a particular domain, and +strive to provide the right level of abstraction first, before going deep. From 9d0e1e4d3e56d9c89f6c961ed9ced82964a6f7b3 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 1 Jul 2025 09:54:51 -0400 Subject: [PATCH 05/15] Add link to t-shaped signals from how to write conventions. --- docs/general/how-to-define-semantic-conventions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index ad143b7445..768f910b3f 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -37,6 +37,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 Convnetions through defining +key use cases for convnentions. + #### Defining attributes Reuse existing attributes when possible. Look through [existing conventions](/docs/registry/attributes/) for similar areas, From 09f64eff839376a85cd51e45ebf33a43d9aa4505 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 9 Jul 2025 11:09:30 -0400 Subject: [PATCH 06/15] Update docs/non-normative/how-to-write-conventions/t-shaped-signals.md Co-authored-by: Steven E. Harris --- docs/non-normative/how-to-write-conventions/t-shaped-signals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 08f7f4d428..5f85dc1fb3 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -14,7 +14,7 @@ block-beta ``` This matches an 80-20 rule, where 80% of users (or use-cases) can leverage the -boardly applicable signals and 20% of users (or use-cases) will dive deep into +broadly applicable signals and 20% of users (or use-cases) will dive deep into a problem with deep signals. ## Broadly Applicable Signals From 2ac71859fe3f35a166b0caadd9c682556977b9f3 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 9 Jul 2025 14:01:18 -0400 Subject: [PATCH 07/15] Update .chloggen/wip-t-shaped-signals.yaml Co-authored-by: Liudmila Molkova --- .chloggen/wip-t-shaped-signals.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/wip-t-shaped-signals.yaml b/.chloggen/wip-t-shaped-signals.yaml index 7fee255ec4..38f0131c95 100755 --- a/.chloggen/wip-t-shaped-signals.yaml +++ b/.chloggen/wip-t-shaped-signals.yaml @@ -7,7 +7,7 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: other +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. From f3fafd72d4abeacb84b3161cf18634bc236ec13d Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 14 Jul 2025 08:32:56 -0400 Subject: [PATCH 08/15] Update docs/general/how-to-define-semantic-conventions.md Co-authored-by: Christophe Kamphaus --- docs/general/how-to-define-semantic-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 768f910b3f..a8a4b40557 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -39,7 +39,7 @@ for new areas or make substantial changes to the existing ones. Please read [T-Shaped Signals](/docs/non-normative/how-to-write-conventions/t-shaped-signals.md) for guidance on how to approach creating Semantic Convnetions through defining -key use cases for convnentions. +key use cases for conventions. #### Defining attributes From fce8a44aae70eeca95dadfd0ba5b4d1561857697 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 14 Jul 2025 08:33:08 -0400 Subject: [PATCH 09/15] Update docs/non-normative/how-to-write-conventions/t-shaped-signals.md Co-authored-by: Christophe Kamphaus --- docs/non-normative/how-to-write-conventions/t-shaped-signals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 5f85dc1fb3..26331b9e19 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -46,7 +46,7 @@ Examples include: ## Recommendations -While defining semantic conventions can be a balance between geneating +While defining semantic conventions can be a balance between generating broadly applicable signals and defining deep at the same time, it is recommended to start with the *broad* use cases and signals for a particular domain, and strive to provide the right level of abstraction first, before going deep. From f93fcd8ea166bf8ca6f3dface62ae78fe03785b1 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 14 Jul 2025 08:40:48 -0400 Subject: [PATCH 10/15] Fixes from review. --- .../t-shaped-signals.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) 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 index 26331b9e19..393e629ce3 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -46,7 +46,16 @@ Examples include: ## Recommendations -While defining semantic conventions can be a balance between generating -broadly applicable signals and defining deep at the same time, it is recommended -to start with the *broad* use cases and signals for a particular domain, and -strive to provide the right level of abstraction first, before going deep. +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. + + + From 62edaaa5e58ea341911f988713441b7bc98bf4c8 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 14 Jul 2025 08:42:08 -0400 Subject: [PATCH 11/15] Fix lint. --- .../non-normative/how-to-write-conventions/t-shaped-signals.md | 3 --- 1 file changed, 3 deletions(-) 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 index 393e629ce3..343cc909aa 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -56,6 +56,3 @@ 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. - - - From b64439155fd31cb056a301d0b6f85510cd4ccfdb Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 15 Jul 2025 08:27:27 -0400 Subject: [PATCH 12/15] Update docs/non-normative/how-to-write-conventions/t-shaped-signals.md Co-authored-by: Steven E. Harris --- docs/non-normative/how-to-write-conventions/t-shaped-signals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 343cc909aa..73ba694ea8 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -14,7 +14,7 @@ block-beta ``` 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 deep into +broadly applicable signals and 20% of users (or use-cases) will dive deeply into a problem with deep signals. ## Broadly Applicable Signals From 17d71b8e93178ecfa6c89f98760964921eedcbf5 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 15 Jul 2025 08:27:36 -0400 Subject: [PATCH 13/15] Update docs/non-normative/how-to-write-conventions/t-shaped-signals.md Co-authored-by: Steven E. Harris --- docs/non-normative/how-to-write-conventions/t-shaped-signals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 73ba694ea8..2780ce4c2c 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -1,6 +1,6 @@ # T-shaped Signals -Semantic Conventions approaches observability with a T-Shaped mindset. This +Semantic Conventions approaches observability with a T-shaped mindset. This splits signals into two types of a "T" shape: ```mermaid From fc3eaf3a3676182d4905a1f033efed5b4233c934 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 15 Jul 2025 08:27:48 -0400 Subject: [PATCH 14/15] Update docs/general/how-to-define-semantic-conventions.md Co-authored-by: Trask Stalnaker --- docs/general/how-to-define-semantic-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index a8a4b40557..64df075fb0 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -38,7 +38,7 @@ 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 Convnetions through defining +for guidance on how to approach creating Semantic Conventions through defining key use cases for conventions. #### Defining attributes From e51b7069d277d846a87179aff8390633d0f73af4 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 15 Jul 2025 08:28:12 -0400 Subject: [PATCH 15/15] Update docs/non-normative/how-to-write-conventions/t-shaped-signals.md Co-authored-by: Steven E. Harris --- docs/non-normative/how-to-write-conventions/t-shaped-signals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 2780ce4c2c..ff6eb287c8 100644 --- a/docs/non-normative/how-to-write-conventions/t-shaped-signals.md +++ b/docs/non-normative/how-to-write-conventions/t-shaped-signals.md @@ -21,7 +21,7 @@ a problem with deep 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 +general-purpose dashboarding, alerting, and diagnostics for HTTP (micro-)services. These signals should provide "horizontal" coverage for observability.