Define VCS span semantic conventions (fixes #3767) by Dipanshusinghh · Pull Request #3793 · open-telemetry/semantic-conventions

Dipanshusinghh · 2026-06-13T05:14:19Z

Closes #3767
This PR defines span conventions for VCS operations as discussed in the issue.
Changes:

model/vcs/registry.yaml - Added vcs.action enum attribute with standard members: clone, fetch, pull, push, checkout.
model/vcs/spans.yaml (new) - Defined VCS span conventions:

Span name pattern: {vcs.action} {vcs.repository.name} (e.g. clone semantic-conventions)
Required attributes: vcs.action, vcs.repository.name
Recommended attributes: server.address, server.port, vcs.ref.head.name, vcs.ref.head.revision, vcs.ref.type, error.type

Cross-VCS naming research - Added a note documenting how the canonical actions (clone, fetch, pull, push, checkout) map to equivalent concepts in SVN, Mercurial, and Perforce, confirming these names are generic and not git-specific.
Span hierarchy guidance - Documented the expected nesting:

VCS spans are child spans of CI/CD pipeline task/step spans (e.g. a "checkout code" step)
HTTP/RPC client spans (underlying network calls) are child spans of the VCS span

.chloggen/define-vcs-span-conventions.yaml - Added changelog entry (type: enhancement, component: vcs).

All changes formatted via prettier and pass the repo's check script.

Dipanshusinghh · 2026-06-13T05:16:16Z

@kamphaus opened PR #3793 for this It covers:

vcs.action enum (clone, fetch, pull, push, checkout)
Span name pattern {vcs.action} {vcs.repository.name} per the convention guidelines
Mapping of these actions to SVN, Mercurial, and Perforce equivalents (per your question on whether these r git-specific)
Span hierarchy: VCS span as child of CI/CD pipeline task span, with HTTP/RPC spans as children of the VCS span

Starting at development stability as discussed. Would appreciate a review whenever you have time.!

- Move action generic mapping to notes on the enum members in registry.yaml - Remove fallback span name format since repository.name is required - Revert unrelated formatting change in .markdownlint-cli2.yaml - Add docs/vcs/README.md and reference it in docs/README.md - Regenerate registry docs using weaver

As decided in the CI/CD SIG meeting on June 16, merge VCS spans under CI/CD section to maintain consistency. - Integrate VCS spans placeholder into docs/cicd/cicd-spans.md - Delete docs/vcs directory - Revert top-level VCS link in docs/README.md - Regenerate registry docs using weaver

…evel-2 heading - Merge in latest main branch changes - Change status in cicd-spans.md from Release Candidate to Mixed - Change VCS client span heading from level-3 to level-2 - Update Table of Contents using doctoc

adrielp · 2026-06-18T13:35:31Z

Sign in to view

+
+**Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span).
+
+The span name SHOULD be `{vcs.action} {vcs.repository.name}`.


What's the reasoning behind including repository name in the span name?

Concerns:

non-normalized repository names

length of repository names

mix of characters separating words (ie. run-build MY_Repository-name)

Loss of queue/exec in the span name.

New question:

What would actually emit a 'VCS' Span? Is there any prototype that exists today for this? I'm struggling to think of what in a VCS repository would create a span associated with a CI/CD pipeline that isn't part of the CI/CD pipeline.

the spec's hierarchy note covers this — VCS span is emitted by the instrumentation inside a pipeline step that runs a git operation (clone, checkout etc). Think of a "Checkout Code" step in GitHub Actions — that step's instrumentation would emit this CLIENT span. It's not a VCS-side concern, it lives within the CI/CD pipeline.

@adrielp
Agred, changing span name to just {vcs.action} makes sense vcs.repository.name is already captured as a required attribute so no information is lost

The span name {vcs.action} {vcs.repository.name} follows the span naming guidance {action} {target}.
For example HTTP spans follow this: GET /orders/{id}.

non-normalized repository names

Since the {vcs.repository.name} attribute already existed, is this currently an issue where it's used?
Should we create a follow-up issue for this?

length of repository names

Should we define a length limit and fallback to just {vcs.action} as span name if exceeded?

mix of characters separating words (ie. run-build MY_Repository-name)
Loss of queue/exec in the span name.

I don't follow this. Given the space in the span name and span hierarchy guidance the task span and vcs span would appropriately separate these concerns.

What would actually emit a 'VCS' Span?

Either the git CLI when Otlp env vars are set could emit such spans or any CI/CD system could emit them (eg. when a checkout step or actions/checkout action is executed).

I'm struggling to think of what in a VCS repository would create a span associated with a CI/CD pipeline that isn't part of the CI/CD pipeline.

As noted we have only defined the client span for use in CI/CD systems or in CLI tools.
We could think of defining corresponding server spans for use VCS-side.
Do you think we should the server span as well?

Thnks for the clarification @kamphaus!
I agree with keeping {vcs.action} {vcs.repository.name} as it aligns with the {action} {target} spec guidelines. Regarding the prototype — is it required to unblock this PR given we're at development stability?

We discussed the requirement for a protype in the general SemConv SIG and CICD SIG meetings.
We should have one for the VCS span conventions.

Ideally the prototype would be for the git CLI tool (for a prototype a fork is sufficient, it does not need to be merged).
I found this prior art around git cli OpenTelemetry: https://github.blog/engineering/architecture-optimization/measuring-git-performance-with-opentelemetry/
Maybe https://github.com/git-ecosystem/trace2receiver could be adapted to emit VCS spans.

@Dipanshusinghh did you have a chance to work on the prototype? It seems to be the main blocker. Thanks!

havent had time for the prototype yet what's the simplest way to unblock this? would a simple sdk script emitting these spans work , or does it have to be git cli integration?

lmolkova · 2026-07-05T16:53:15Z

+      **Span Hierarchy:**
+      When integrated into CI/CD pipelines, VCS spans SHOULD be modeled as child spans of the CI/CD pipeline task/step execution spans (e.g., a task span representing a "checkout code" step).
+      Any underlying HTTP client or RPC spans representing the actual network communication with the VCS server/provider SHOULD be modeled as child spans of the VCS span.


It's not possible to control span hierarchy in practice, especially when they come from different instrumentations. The hierarchy depends fully on the caller implementation and set of enabled instrumentations.

Suggested change

**Span Hierarchy:**

When integrated into CI/CD pipelines, VCS spans SHOULD be modeled as child spans of the CI/CD pipeline task/step execution spans (e.g., a task span representing a "checkout code" step).

Any underlying HTTP client or RPC spans representing the actual network communication with the VCS server/provider SHOULD be modeled as child spans of the VCS span.

makes sense, removed span hierarchy notes completely

lmolkova · 2026-07-05T16:54:31Z

+        requirement_level: recommended
+      - ref: vcs.ref.type
+        requirement_level: recommended
+      - ref: server.address


server address of what? Please update brief or note to explain what the endpoint is

updated brief it means the vcs provider host like github.com

lmolkova · 2026-07-05T17:01:48Z

+    span_kind: client
+    stability: development
+    brief: >
+      This span describes a Version Control System (VCS) operation client.


what is the VCS operation client ? If it's a library, do we ask CI/CD pipelines to enable instrumentation? if it's a CLI, do we want them to be instrumented natively?

This goes back to the prototypes discussion in another comment.

added note to spans.yaml, client spans are mostly from cicd tasks (clone/checkout) or git cli wrapper tools

lmolkova · 2026-07-05T17:04:08Z

+    note: |
+      **Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span).
+
+      The span name SHOULD be `{vcs.action} {vcs.repository.name}`.


The name may depend on the operation.

E.g. you clone a repo, so name is clone my-repo, but you can pull a branch and then name would be pull my-branch or pull my-repo my-branch

make naming guide more flexible. so now it can be operation + repo name or operation _+ branch depending on operation

lmolkova · 2026-07-05T17:11:36Z

            "gitea",
            "bitbucket",
          ]
+      - id: vcs.action


not a strong opinion, in other conventions we call these things *.operation.name and usually we end up relaxing enum so that individual systems use their own terminology.

E.g. perforce users would appreciate seeing the command that was actually called (like sync) instead of unified version.

The unification would come through two options:

(preferred, but more tedious) define individual span type for each class of operation. Define attributes that are only applicable to this type. E.g. no branch name on clone. We're going down this road in GenAI semconv Span + metric definitions principles for agents, inference, control plane semantic-conventions-genai#249. This should eventually will go over the wire via Introduce span identity that can be used by the consumers #2055

(legacy) Add dedicated vcs.operation.type attribute - this was done in messaging https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#operation-types

renamed it to vcs.operation.name & changed type to string now tools can use their own names like sync or update

…ess brief, and span name guidelines

Dipanshusinghh requested review from a team as code owners June 13, 2026 05:14

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

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

github-actions Bot added enhancement New feature or request area:vcs labels Jun 13, 2026

Dipanshusinghh force-pushed the vcs-span-conventions branch from db69deb to 025a004 Compare June 13, 2026 05:24

Define VCS span semantic conventions (fixes open-telemetry#3767)

a65eccb

Dipanshusinghh force-pushed the vcs-span-conventions branch from 025a004 to a65eccb Compare June 13, 2026 05:27

Fix markdownlint and doctoc checks for VCS spans

bb54c80

thompson-tomo reviewed Jun 14, 2026

View reviewed changes

Comment thread model/vcs/spans.yaml Outdated

Comment thread .markdownlint-cli2.yaml Outdated

Comment thread model/vcs/spans.yaml Outdated

kamphaus reviewed Jun 14, 2026

View reviewed changes

Comment thread model/vcs/spans.yaml Outdated

Comment thread model/vcs/spans.yaml Outdated

Comment thread docs/vcs/vcs-spans.md Outdated

kamphaus added this to CI/CD SemConv: Phase 2 Jun 14, 2026

kamphaus moved this to In Progress in CI/CD SemConv: Phase 2 Jun 14, 2026

kamphaus moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Jun 14, 2026

Dipanshusinghh requested review from kamphaus and thompson-tomo June 15, 2026 15:22

kamphaus reviewed Jun 16, 2026

View reviewed changes

Comment thread docs/cicd/cicd-spans.md

Comment thread docs/cicd/cicd-spans.md Outdated

Comment thread model/vcs/spans.yaml Outdated

Dipanshusinghh added 2 commits June 17, 2026 04:12

Merge remote-tracking branch 'upstream/main' into vcs-span-conventions

1d885ad

kamphaus approved these changes Jun 17, 2026

View reviewed changes

adrielp reviewed Jun 18, 2026

View reviewed changes

Dipanshusinghh requested a review from adrielp June 18, 2026 13:48

adrielp mentioned this pull request Jun 30, 2026

Define VCS span conventions #3767

Open

lmolkova requested changes Jul 5, 2026

View reviewed changes

github-project-automation Bot moved this from Awaiting codeowners approval to Blocked in Semantic Conventions Triage Jul 5, 2026

Dipanshusinghh added 3 commits July 5, 2026 23:15

Merge upstream main and resolve conflicts

bce341c

fix(vcs): apply maintainer feedback on spans and attributes

559667f

chore(docs): regenerate markdown files to fix CI

47d5dec

Dipanshusinghh requested review from a team as code owners July 5, 2026 17:54

Dipanshusinghh added 7 commits July 5, 2026 23:24

chore(docs): regenerate system metrics markdown

5661b68

chore(docs): remove accidentally generated model.md

1851ab2

chore(docs): regenerate markdown with correct registry base url param

542ece9

fix(docs): remove extra blank lines to fix markdownlint MD012

9e4c466

fix(docs): regenerate registry docs to sync with yaml

93a861a

fix(vcs): apply maintainer feedback on spans description, server addr…

0ccb3ea

…ess brief, and span name guidelines

fix(yamllint): wrap long lines in spans.yaml to pass yamllint

068035d

Dipanshusinghh requested a review from lmolkova July 6, 2026 02:46


		Span name MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span).

		The span name SHOULD be `{vcs.action} {vcs.repository.name}`.

	Span Hierarchy:
	When integrated into CI/CD pipelines, VCS spans SHOULD be modeled as child spans of the CI/CD pipeline task/step execution spans (e.g., a task span representing a "checkout code" step).
	Any underlying HTTP client or RPC spans representing the actual network communication with the VCS server/provider SHOULD be modeled as child spans of the VCS span.

Uh oh!

Conversation

Dipanshusinghh commented Jun 13, 2026

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

kamphaus Jun 18, 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!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as duplicate.

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Dipanshusinghh commented Jun 13, 2026 •

edited

Loading

kamphaus Jun 18, 2026 •

edited

Loading