feat(ARSN-592): expose manual instrumentation API in lib/tracing

[delthas]

Summary

Adds startApiSpan(action) to lib/tracing alongside the existing instrumentApiMethod — a manual-lifecycle helper for consumers whose dispatch site owns the span start + end points directly.

export interface ApiSpan {
    end(err?: any): void;
    withContext<T>(fn: () => T): T;
}

export function startApiSpan(action: string): ApiSpan;

• Span name api.<action> (same SPAN_PREFIX as instrumentApiMethod).
• end(err?) reuses the existing exported endSpan(span, err?) so the recordException + status + error.type ceremony stays in one place. Same err-as-optional convention.
• withContext(fn) runs fn with the span set on the active context so child auto-spans (mongo, ioredis, http) nest underneath.
• OTEL-off: returns a no-op object — no @opentelemetry/api load.

Motivation

VAULT-708 consumes the tracing module via vault PR #203. Reviewer feedback (thread) pointed out that instrumentApiMethod's wrap-once-at-module-load shape — natural for cloudserver's flat `api[name]=handler` table — forces vault to add a per-Route wrap cache + a static-this `.bind` dance + a new lazy method on Route just to amortize a wrap on a single centralized dispatch site (`Router._startRequest`). `startApiSpan` lets vault call the helper inline at the dispatch site instead, no caching layer needed.

Both APIs produce the same span output and share the underlying `endSpan` ceremony; the choice is stylistic at the consumer.

Tests

5 new unit tests in `tests/unit/tracing/instrumentation.spec.js` (13 total in the file):

• `end()` on success → span ends with status OK
• `end(err)` → span ends with status ERROR + `error.type` from `err.code`
• `withContext(fn)` sets the started span as the active context inside `fn` (asserted by running inside an outer span and checking the active span flips correctly before / inside / after)
• `withContext(fn)` returns the value `fn` returns
• OTEL-off returns a no-op object — `end()`, `end(err)`, `withContext` all safe

Related

• Parent: ARSN-586 — the original tracing module (#2632)
• Consumer: VAULT-708 / scality/vault2#203

Issue: ARSN-592

[bert-e]

Hello delthas,

My role is to assist you with the merge of this
pull request. Please type @bert-e help to get information
on this process, or consult the user documentation.

Available options

name	description	privileged	authored
/after_pull_request	Wait for the given pull request id to be merged before continuing with the current one.
/bypass_author_approval	Bypass the pull request author's approval	⭐
/bypass_build_status	Bypass the build and test status	⭐
/bypass_commit_size	Bypass the check on the size of the changeset TBA	⭐
/bypass_incompatible_branch	Bypass the check on the source branch prefix	⭐
/bypass_jira_check	Bypass the Jira issue check	⭐
/bypass_peer_approval	Bypass the pull request peers' approval	⭐
/bypass_leader_approval	Bypass the pull request leaders' approval	⭐
/approve	Instruct Bert-E that the author has approved the pull request.		✍️
/create_pull_requests	Allow the creation of integration pull requests.
/create_integration_branches	Allow the creation of integration branches.
/no_octopus	Prevent Wall-E from doing any octopus merge and use multiple consecutive merge instead
/unanimity	Change review acceptance criteria from one reviewer at least to all reviewers
/wait	Instruct Bert-E not to run until further notice.

Available commands

name	description	privileged
/help	Print Bert-E's manual in the pull request.
/status	Print Bert-E's current status in the pull request TBA
/clear	Remove all comments from Bert-E from the history TBA
/retry	Re-start a fresh build TBA
/build	Re-start a fresh build TBA
/force_reset	Delete integration branches & pull requests, and restart merge process from the beginning.
/reset	Try to remove integration branches unless there are commits on them which do not appear on the source branch.

Status report is not available.

[bert-e]

Waiting for approval

The following approvals are needed before I can proceed with the merge:

• the author

• 2 peers

[bert-e]

Conflict

There is a conflict between your branch improvement/ARSN-592/manual-instrumentation-api and the
destination branch development/8.4.

Please resolve the conflict on the feature branch (improvement/ARSN-592/manual-instrumentation-api).

git fetch && \
git checkout origin/improvement/ARSN-592/manual-instrumentation-api && \
git merge origin/development/8.4

Resolve merge conflicts and commit

git push origin HEAD:improvement/ARSN-592/manual-instrumentation-api

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 73.94%. Comparing base (97edb92) to head (bf94ffc).

Files with missing lines	Patch %	Lines
lib/tracing/index.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@               Coverage Diff                @@
##           development/8.4    #2639   +/-   ##
================================================
  Coverage            73.94%   73.94%           
================================================
  Files                  229      229           
  Lines                18483    18495   +12     
  Branches              3823     3849   +26     
================================================
+ Hits                 13667    13676    +9     
- Misses                4811     4814    +3     
  Partials                 5        5           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bert-e]

Waiting for approval

The following approvals are needed before I can proceed with the merge:

• the author

• 2 peers

[claude]

LGTM

Review by Claude Code