feat(http): migrate HTTP conventions to Weaver schema v2 - Closes #3809 by Dipanshusinghh · Pull Request #3827 · open-telemetry/semantic-conventions

Dipanshusinghh · 2026-06-26T12:18:11Z

Closes #3809

Migrated 6 HTTP YAML files from Weaver v1 to v2 format:

Added file_format: definition/2 to all files
Converted groups: to attribute_groups:, spans:, metrics:, events:
Changed extends: to ref_group:
Changed id: to key: (attributes) and name: (spans/metrics)
Added visibility: public and stability: development to attribute groups

This is a prototype migration as described in the issue.
Open to feedback on any gaps or improvements needed.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
AI-assisted: Used AI to understand v2 schema, all changes done manually.
I have the experience and knowledge necessary to understand, review, and validate all content in this PR.

github-actions · 2026-06-26T12:18:32Z

👋 Thanks for your contribution!

This PR modifies file(s) in area(s) that do not currently have an active SIG/project:

http
http

Per the area ownership process,
changes to these areas need an active SIG/project, so this PR has been automatically
closed and labeled triage:rejected:declined.

This does not mean your change is unwelcome:

For substantial changes or new conventions: Consider starting a new SIG/project.
See the Project Management guide.
If you believe this was closed in error: Please reach out in the
#otel-semantic-conventions channel on the CNCF Slack.

Thanks again for taking the time to contribute! 🙏

thompson-tomo

Alot of content and information would be lost with this change. At the same time un-necessary changes are bloating the diff and in fact they can lead to ci check failures. Take a look at my comments for the instances of issues which appear many times.

Please also regenerate the docs to provide context on impact to reader of the docs.

thompson-tomo

Still a handful of unrelated/unnecessary changes which are causing issues. Please ensure after all yaml changes you are regenerating docs which will help to identify the CI issues earlier

…_level to spans and events

thompson-tomo

Looking at the way public attribute groups have been used just for docs, we should be tackling #3836 first. That would enable avoidance of the public groups while still maintaining deprecated in different tables to non deprecated.

thompson-tomo · 2026-06-30T01:22:24Z

-cascade:
-  body_class: otel-docs-spec
-  github_repo: &repo https://github.com/open-telemetry/semantic-conventions
-  github_subdir: docs
-  path_base_for_github_subdir: tmp/semconv/docs/
-  github_project_repo: *repo
-redirects:
-  - { from: 'attributes-registry/*', to: 'registry/attributes/:splat' }
-  - { from: 'database/*', to: 'db/:splat' }
-cSpell:ignore: semconv
-auto_gen: below
-linkTitle: Semantic conventions
+weight: -2
 --->

-# OpenTelemetry semantic conventions
+# Registry

-The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it.
-The Semantic Conventions specify among other things span names and kind, metric instruments and units as well as attribute names, types, meaning and valid values. For a detailed definition of the Semantic Conventions' scope see [Semantic Conventions Stability](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability).
-The benefit to using Semantic Conventions is in following a common naming scheme that can be standardized across a codebase, libraries, and platforms. This allows easier correlation and consumption of data.
+This is an automatically generated registry of available semantic conventions.

-Semantic Conventions are defined for the following areas:
-
-* **[General](general/README.md): General Semantic Conventions**.
-* [CI/CD](cicd/README.md): Semantic Conventions for CI/CD systems.
-* [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries.
-* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
-* [Database](db/README.md): Semantic Conventions for database operations.
-* [Exceptions](exceptions/README.md): Semantic Conventions for exceptions.
-* [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations.
-* [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations.
-* [Generative AI](gen-ai/README.md): Moved to the [OpenTelemetry GenAI semantic conventions repository](https://github.com/open-telemetry/semantic-conventions-genai).
-* [GraphQL](graphql/README.md): Semantic Conventions for GraphQL implementations.
-* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
-* [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems.
-* [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations.
-* [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations.
-* [System](system/README.md): System Semantic Conventions.
-
-Semantic Conventions by signals:
-
-* [Events](general/events.md): Semantic Conventions for event data.
-* [Logs](general/logs.md): Semantic Conventions for logs data.
-* [Metrics](general/metrics.md): Semantic Conventions for metrics.
-* [Profiles](general/profiles.md): Semantic Conventions for profiles.
-* [Resource](resource/README.md): Semantic Conventions for resources.
-* [Trace](general/trace.md): Semantic Conventions for traces and spans.
-
-Configuration:
-
-* [Configuration](configuration/README.md): Semantic convention related configuration options.
-
-Also see:
-
-* [How to write semantic conventions](how-to-write-conventions/README.md)
-* [Non-normative supplementary information](non-normative/README.md)
+- [Attributes](attributes/README.md)
+- [Entities](entities/README.md)


This should not be changed

thompson-tomo · 2026-06-30T01:23:11Z


 **[1] `http.request.header.<key>`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured.
 Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
-


Why is this being changed

thompson-tomo · 2026-06-30T01:24:01Z


 | Key | Stability | Value Type | Description | Example Values |
 | --- | --- | --- | --- | --- |
-| <a id="http-client-ip" href="#http-client-ip">`http.client_ip`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `client.address`. | string | Deprecated, use `client.address` instead. | `83.164.160.102` |


Why is this being changed

thompson-tomo · 2026-06-30T01:26:32Z

+    visibility: public
+    stability: development


Why this change? This seems really odd.

thompson-tomo · 2026-06-30T01:28:50Z

+  - name: http.client.request.exception
    stability: development
-    type: event
+    requirement_level: recommended


Is this a nice to have change or a required? If not required, leave out.

thompson-tomo · 2026-06-30T01:30:50Z

-          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-


Why is it being removed?

thompson-tomo · 2026-06-30T01:33:17Z

+    visibility: public
+    stability: stable


Why public & stable?

Dipanshusinghh · 2026-06-30T04:27:09Z

Looking at the way public attribute groups have been used just for docs, we should be tackling #3836 first. That would enable avoidance of the public groups while still maintaining deprecated in different tables to non deprecated.

Thanks for the review @thompson-tomo!

Public attribute_groups: Yeah, you're right this was just a quick hack to stop Weaver v2 from dumping root attributes into a fallback model.md & failing CI. Want me to block this PR on #3836 and revert this, or keep it to unblock CI?

Missing server.address note: Ah, my bad! Accidentally dropped it during the ref conversion. I'll restore it.
events.yaml requirement_level: Had to add this to pass strict CI validation (it was throwing a fatal error).
http.md formatting & redundant note: The formatting changes were auto-generated by Weaver. I'll remove the redundant note in registry-deprecated.yaml.
Let me know on [chore] switch weaver to builtin attribute filter #3836, and I'll push the other fixes!

thompson-tomo · 2026-06-30T04:56:55Z

The problem with the quick hack, once it is merged and released we are stuck having it and it can only be removed via a breaking change.

I suspect we will need to wait for my pr to land as that way we can ensure that when we are switching a namespace etc we can ensure the docs are as easy as possible to review without un-necessary changes.

I have just gone and commented on my pr with the instances of meaningful text disappearing from docs.

We should also potentially add an attribute group registry so that the text is still visible to a reader & can remain in the docs.

…store missing note

Dipanshusinghh · 2026-07-01T03:31:11Z

The problem with the quick hack, once it is merged and released we are stuck having it and it can only be removed via a breaking change.

I suspect we will need to wait for my pr to land as that way we can ensure that when we are switching a namespace etc we can ensure the docs are as easy as possible to review without un-necessary changes.

I have just gone and commented on my pr with the instances of meaningful text disappearing from docs.

We should also potentially add an attribute group registry so that the text is still visible to a reader & can remain in the docs.

Hey @thompson-tomo, I've pushed the requested fixes (removed the attribute_groups hack and kept the required note: fields), but the CI is still failing on markdown generation due to that root attributes bug.

I've been stuck trying to find a workaround for it. Do you have any better solution to get the CI green right now, or should we just leave this PR blocked until your PR #3836 is merged?

thompson-tomo · 2026-07-01T05:07:07Z

@Dipanshusinghh can you fix what i just commented and if the notes are required on deprecation add the missing ` to the note to bring the diff down.

Also review the diff to check un-necessary changes ie the root readme.

thompson-tomo · 2026-07-01T04:54:10Z

-    type: attribute_group
-    display_name: Deprecated HTTP Attributes
+    visibility: internal
+    stability: development


Suggested change

stability: development

thompson-tomo · 2026-07-01T14:23:37Z

+attribute_groups:
  - id: registry.http.deprecated
-    type: attribute_group
-    display_name: Deprecated HTTP Attributes
+    visibility: internal
+    stability: development
    brief: "Describes deprecated HTTP attributes."


Actually why can't we just remove the group altogether?

Makes sense.

thompson-tomo · 2026-07-01T14:25:13Z

+    deprecated:
+      reason: renamed
+      renamed_to: http.request.method
+      note: "Replaced by http.request.method."


These need the backticks to minimise diff ie

Suggested change

note: "Replaced by http.request.method."

note: "Replaced by `http.request.method`."

If they need to be added.

thompson-tomo · 2026-07-01T14:29:48Z

+attribute_groups:
+  - id: registry.http
+    visibility: internal
+    stability: development
+    brief: "This document defines semantic convention attributes in the HTTP namespace."
+


We don't actually need this, lets remove

thompson-tomo · 2026-07-01T14:32:22Z

+      - ref: server.address
+        requirement_level: opt_in
+        note: |
+          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
+
+          > [!WARNING]
+          > Since this attribute is based on HTTP headers, opting in to it may allow an attacker
+          > to trigger cardinality limits, degrading the usefulness of the metric.
+      - ref: server.port
+        requirement_level: opt_in
+        note: |
+          See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).


The purpose of attribute groups is to avoid adding all this duplication, let's put the old group back and use that.

…ks, and redundant groups

kamphaus · 2026-07-01T20:08:31Z

 - [Mainframe](mainframe.md)
 - [MCP](mcp.md)
 - [Messaging](messaging.md)
+- [Model](model.md)


Where did this come from?
There is no model.md file.

See explanation in #3827 (comment) & in https://github.com/open-telemetry/semantic-conventions/actions/runs/28536373665/job/84598652922#step:3:1 shows it would be removed along with http, but now adds a home namespace. Hence my pr #3836 to switch to the standard attribute filter.

thompson-tomo · 2026-07-02T04:09:26Z

@Dipanshusinghh please take the changes from thompson-tomo@a0c77f4 and add to your branch as i can't raise a pr for your fork.

Note the ci will still fail with link checks etc but it shows what you are blocked on.

My pr #3836 will address those issues and it avoids the current need to rename the registry file

thompson-tomo · 2026-07-02T05:36:21Z

+    deprecated:
+      reason: renamed
+      renamed_to: http.request.method
+      note: "Replaced by `http.request.method`."


Strange that these are now required, have logged open-telemetry/weaver#1556 as this will be adding alot of un-necessary boilerplate.

Hey @thompson-tomo,

Thanks for the help! Ihave fetched and applied your commit (a0c77f4) to my branch as requested.

I see the CI is still failing on link checks as expected due to the Weaver definition/2 issue i understand that this PR is now blocked until your PR #3836 is merged to fix the underlying tool issue
thnx for the help !

Correct this is now blocked until we have a solution for the attributes in the wrong namespace issue which my pr solves.

I have managed to descope my pr to avoid namespaces which had meaningful text which should make it easier to review.

thompson-tomo · 2026-07-02T13:09:17Z

+    kind: client
+    requirement_level: recommended
+    name:
+      note: "{http.request.method}"


This should be a copy of what is in the span note field.

thompson-tomo · 2026-07-02T13:09:51Z

+    kind: server
+    requirement_level: recommended
+    name:
+      note: "{http.request.method} {http.route}"


This should be a copy of what is in the span note field.

joaopgrassi · 2026-07-07T14:43:20Z

Hi @Dipanshusinghh turns out we are not so ready to start migrating stuff as I thought we were. I'm closing this for now, we are re-grouping and looking into the new plan (see parent issue).

Migrate HTTP conventions to Schema v2 (definition/2)

84f4b2b

Dipanshusinghh requested review from a team as code owners June 26, 2026 12:18

github-project-automation Bot added this to Semantic Conventions Triage Jun 26, 2026

github-project-automation Bot moved this to Untriaged in Semantic Conventions Triage Jun 26, 2026

github-actions Bot added the triage:rejected:declined label Jun 26, 2026

github-actions Bot closed this Jun 26, 2026

joaopgrassi added triage:accepted:ready and removed triage:rejected:declined labels Jun 26, 2026

joaopgrassi reopened this Jun 26, 2026

thompson-tomo reviewed Jun 26, 2026

View reviewed changes

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from 29617ec to dddb052 Compare June 28, 2026 21:41

Dipanshusinghh requested review from a team as code owners June 28, 2026 21:41

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from dddb052 to 3c54745 Compare June 28, 2026 22:07

thompson-tomo reviewed Jun 29, 2026

View reviewed changes

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch 2 times, most recently from 7813a45 to 55642d6 Compare June 29, 2026 19:01

github-actions Bot added the area:http label Jun 29, 2026

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from 55642d6 to 0bb3cdd Compare June 29, 2026 19:17

github-actions Bot added the enhancement New feature or request label Jun 29, 2026

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch 4 times, most recently from c542d87 to 444a48b Compare June 29, 2026 19:48

fix(http): fully migrate to v2 schema and address reviewer feedback

d9fb64c

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from 444a48b to d9fb64c Compare June 29, 2026 19:59

chore(docs): regenerate registry markdown and add missing requirement…

b6e0ec3

…_level to spans and events

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from b6e0ec3 to 5ecc384 Compare June 29, 2026 20:23

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from 5ecc384 to 9ae79cd Compare June 29, 2026 20:41

fix(http): add missing requirement_levels and fix markdown generation

c4021e7

Dipanshusinghh force-pushed the migrate-http-conventions-v2 branch from 9ae79cd to c4021e7 Compare June 29, 2026 20:44

thompson-tomo reviewed Jun 30, 2026

View reviewed changes

Dipanshusinghh added 3 commits July 1, 2026 08:33

fix(http): address reviewer feedback, revert attribute_group hack, re…

9b17df4

…store missing note

chore(docs): fix markdownlint errors in generated http.md

166e85a

fix(http): restore note fields for deprecated attributes and fix MD012

d9a7cda

thompson-tomo reviewed Jul 1, 2026

View reviewed changes

Dipanshusinghh added 2 commits July 1, 2026 20:18

fix(http): address maintainer review feedback on duplication, backtic…

590d1c8

…ks, and redundant groups

fix(http): remove brief property from internal attribute groups

f973efb

kamphaus reviewed Jul 1, 2026

View reviewed changes

thompson-tomo reviewed Jul 2, 2026

View reviewed changes

fix(http): apply maintainer changes for docs CI block

26b6fd9

thompson-tomo mentioned this pull request Jul 2, 2026

[chore] switch weaver to builtin attribute filter #3836

Open

7 tasks

thompson-tomo reviewed Jul 2, 2026

View reviewed changes

fix(http): use link to docs for span name note

440e308

joaopgrassi closed this Jul 7, 2026


		[1] `http.request.header.<key>`: Instrumentations SHOULD require an explicit configuration of which headers are to be captured.
		Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.

		See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).

	note: "Replaced by http.request.method."
	note: "Replaced by `http.request.method`."

Uh oh!

Conversation

Dipanshusinghh commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge requirement checklist

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

thompson-tomo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thompson-tomo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thompson-tomo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Dipanshusinghh commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thompson-tomo commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Dipanshusinghh commented Jul 1, 2026

Uh oh!

thompson-tomo commented Jul 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Dipanshusinghh commented Jun 26, 2026 •

edited

Loading

thompson-tomo left a comment •

edited

Loading

Dipanshusinghh commented Jun 30, 2026 •

edited

Loading

thompson-tomo commented Jun 30, 2026 •

edited

Loading

thompson-tomo Jul 2, 2026 •

edited

Loading

thompson-tomo commented Jul 2, 2026 •

edited

Loading

thompson-tomo Jul 2, 2026 •

edited

Loading