[db/oracledb] Add application context piggyback for oracle database by sudarshan12s · Pull Request #3901 · open-telemetry/semantic-conventions

sudarshan12s · 2026-07-16T18:10:49Z

Fixes #

Changes

This PR enhances the Oracle Database (oracledb) semantic conventions by documenting a modern Application Context Piggyback mechanism for context propagation.

New Context Propagation Strategy: Adds documentation for using driver-level application context piggybacking within the CLIENTCONTEXT namespace using the key ora$opentelem$tracectx (and optionally ora$opentelem$baggage).
Limitations: Highlights client driver/server compatibility constraints and explicitly notes current server-side parsing limitations for tracestate and baggage to handle future-proofing gracefully.
Examples: Provided a native Java (oracle.jdbc) connection tracing API usage and also a complete application configuration example using .NET (Oracle.ManagedDataAccess.Core).
Comparison: Explicitly details why this approach is preferred over V$SESSION.ACTION (avoids overloading application fields and bypasses the 64-byte limitation).

Important

Pull request acceptance is subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above may be automatically rejected and closed.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Links to prototypes or existing instrumentations (when adding or changing conventions)
Disclose AI usage, see OTel GenAI policy:
- no AI used
- AI-assisted
- bulk AI-generated
I have the experience and knowledge necessary to understand, review, and validate all content in this PR.¹

Yes, I can answer maintainer questions about the content of this PR without using AI. ↩

Copilot

Pull request overview

This PR extends the existing Oracle Database (oracledb) semantic conventions documentation by adding guidance for propagating trace context via Oracle driver “Application Context Piggyback” (CLIENTCONTEXT), and by recommending it over V$SESSION.ACTION when supported.

Changes:

Document a new “Application context piggyback” context propagation strategy, including a specified wire-format for traceparent/tracestate (and optional baggage).
Add a .NET (Oracle.ManagedDataAccess.Core) configuration example demonstrating opt-in driver-side propagation.
Update the V$SESSION.ACTION section to recommend piggybacking when available, and add a changelog entry.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
docs/db/oracledb.md	Adds a new context propagation section for application context piggybacking, examples, and guidance vs `V$SESSION.ACTION`.
.chloggen/oracledb-app-context.yaml	Adds a release note entry for the Oracle DB enhancement.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

lmolkova · 2026-07-17T18:34:43Z

+        // 2. Opt-in to client context piggybacking.
+        // The driver automatically serializes the active W3C trace context
+        // into CLIENTCONTEXT (ora$opentelem$tracectx) during subsequent executions.
+        connection.DatabaseOpenTelemetryTracing = true;


lmolkova

That's awesome!

I'd like to check if we can deprecate or remove V$SESSION section

lmolkova · 2026-07-17T18:43:59Z

+
+Although application context piggyback is not constrained by the 64 byte limit of `V$SESSION.ACTION`, it can still be subject to application context size limits. Oracle application context values are limited to 4000 bytes, and drivers such as `node-oracledb` may enforce the same limit in their APIs. Furthermore, this mechanism requires support from both the database client driver and the database server version in use. To successfully capture and process these values for end-to-end tracing, the database server must also be explicitly configured to enable tracing.
+
+Compared with `V$SESSION.ACTION`, application context piggyback avoids overloading a field that applications may already use and is not constrained by the 64 byte limit of `ACTION`.


I'd be in favor of deprecating V$SESSION section give there is a blessed-by-provider way to propagate context now.

@sincejune @XSAM @open-telemetry/semconv-db-approvers wdyt?

@sudarshan12s are there cases when V$SESSION.ACTION is preferred / necessary? Can we provide an explicit recommendation to use new way over that?

Hi @lmolkova, I've updated the document to address this. The V$SESSION.ACTION approach is now explicitly designated for older Oracle versions only.

I have added the exact minimum client and server versions required for the new Application Context Piggyback mechanism, along with a new Recommendation Guidance section details.

Please see.

@sudarshan12s Is it possible to read traceparent from V$SESSION after using piggybacks?

The oracledbreceiver currently uses V$SESSION to sample running queries. The samples include information such as the query plan and blocking sessions. If not, then using only piggybacks would break the query sample feature of oracledbreceiver.

Or, is there a way to make spans from oracledb publish this type of information?

… into appcontextpiggybackspec

propogation is supported.

table

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

docs/db/oracledb.md:1

The normative language here is internally inconsistent and overly strict: a universal “MUST prioritize” conflicts with earlier text that frames piggybacking as optional/opt-in and dependent on driver/server support. Consider changing the requirement to conditional language (e.g., “SHOULD prefer when supported/available”) and avoid calling V$SESSION.ACTION “deprecated” unless the repo has a formal deprecation process/marker for this section.

<!--- Hugo front matter used to generate the website version of this page:

sudarshan12s · 2026-07-21T13:30:20Z


+### Choice of Propagation Mechanism
+
+When selecting a context propagation strategy for Oracle Database, telemetry implementations MUST prioritize the **Application Context Piggyback** mechanism over the legacy `V$SESSION.ACTION` method.


I can address them after review of updated changes.

sudarshan12s · 2026-07-20T16:35:53Z

+
+| Mechanism | Implementation Type | Minimum Stack Requirements | Tracing Behavior |
+| :--- | :--- | :--- | :--- |
+| **Application Context Piggyback (Recommended)** | **Native** | • **Client:** Oracle JDBC Driver 23.26.2+ or ODP.NET (managed or core) 23.26.2+<br><br>• **Server:** Oracle AI Database 26ai 23.26.2+ | Built-in server-side parsing of W3C telemetry context via the network protocol. |


26ai is generally the release name and 23.26.2+ is the specific version from where its supported.

opentelemetry-pr-dashboard · 2026-07-21T12:39:32Z

Pull request dashboard status

Status last refreshed: 2026-07-25 18:00:13 UTC.

Waiting on: Author
Next step: Address or respond to 2 review feedback items:
- Inline threads: 1, 2
- For each item, reply to move the discussion forward, e.g. link to the commit that addresses it, explain why no change is needed, or ask a follow-up question.

This automated status or its linked feedback items may be incorrect. If something looks wrong, please report it with the result you expected. If you believe this pull request is incorrectly routed as waiting on the author, comment /dashboard route:reviewers to route it from waiting on the author to waiting on reviewers. If the last refreshed time above predates your latest reply or push, the dashboard hasn't processed it yet.

- Inintial changes for application context support

c5b51fd

Copilot AI review requested due to automatic review settings July 16, 2026 18:10

sudarshan12s requested review from a team as code owners July 16, 2026 18:10

github-project-automation Bot added this to Semantic Conventions Triage Jul 16, 2026

github-project-automation Bot moved this to Untriaged in Semantic Conventions Triage Jul 16, 2026

github-actions Bot added enhancement New feature or request area:db labels Jul 16, 2026

Copilot started reviewing on behalf of sudarshan12s July 16, 2026 18:11 View session

- update PR number

4eb032f

Copilot AI reviewed Jul 16, 2026

View reviewed changes

Comment thread docs/db/oracledb.md Outdated

Comment thread docs/db/oracledb.md Outdated

Comment thread docs/db/oracledb.md Outdated

Comment thread docs/db/oracledb.md Outdated

Comment thread .chloggen/oracledb-app-context.yaml Outdated

Comment thread .chloggen/oracledb-app-context.yaml Outdated

sudarshan12s and others added 2 commits July 16, 2026 23:46

Potential fix for pull request finding

37048a8

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

- Address review comments

dfe04ef

sudarshan12s requested a review from Copilot July 17, 2026 04:04

Copilot started reviewing on behalf of sudarshan12s July 17, 2026 04:05 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread docs/db/oracledb.md Outdated

Potential fix for pull request finding

cb0b6d9

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

sudarshan12s requested a review from Copilot July 17, 2026 04:42

Copilot started reviewing on behalf of sudarshan12s July 17, 2026 04:43 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread docs/db/oracledb.md

- simplified .NET example

c906f1d

lmolkova moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Jul 17, 2026

lmolkova reviewed Jul 17, 2026

View reviewed changes

kamphaus reviewed Jul 18, 2026

View reviewed changes

Comment thread .chloggen/oracledb-app-context.yaml Outdated

Comment thread docs/db/oracledb.md

sudarshan12s added 4 commits July 19, 2026 13:30

Merge branch 'main' of github.com:open-telemetry/semantic-conventions…

0108c1b

… into appcontextpiggybackspec

- update jdbc client version and DB version where new way of context

c0ff112

propogation is supported.

- update supported DB versions

b2b90e4

- update the links for .NET and minor changes in Propagation Mechanism

524dfa6

table

sudarshan12s requested review from Copilot, kamphaus and lmolkova July 20, 2026 15:58

Copilot AI reviewed Jul 20, 2026

View reviewed changes

Copilot started reviewing on behalf of sudarshan12s July 20, 2026 16:55 View session

opentelemetry-pr-dashboard Bot mentioned this pull request Jul 21, 2026

Pull Request Dashboard #3912

Open


		Although application context piggyback is not constrained by the 64 byte limit of `V$SESSION.ACTION`, it can still be subject to application context size limits. Oracle application context values are limited to 4000 bytes, and drivers such as `node-oracledb` may enforce the same limit in their APIs. Furthermore, this mechanism requires support from both the database client driver and the database server version in use. To successfully capture and process these values for end-to-end tracing, the database server must also be explicitly configured to enable tracing.

		Compared with `V$SESSION.ACTION`, application context piggyback avoids overloading a field that applications may already use and is not constrained by the 64 byte limit of `ACTION`.


		### Choice of Propagation Mechanism

		When selecting a context propagation strategy for Oracle Database, telemetry implementations MUST prioritize the Application Context Piggyback mechanism over the legacy `V$SESSION.ACTION` method.

Uh oh!

Conversation

sudarshan12s commented Jul 16, 2026

Changes

Merge requirement checklist

Footnotes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

lmolkova Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

lmolkova Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

sudarshan12s Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

XSAM Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

sudarshan12s Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

sudarshan12s Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

opentelemetry-pr-dashboard Bot commented Jul 21, 2026 •

edited

Loading