Expose generic fallback span tags

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [7.5.0] - 2026-07-28
+### Added
+- Add a generic `IUserLandTracer.setFallbackSpanTag` API and exported GraphQL operation tag constants.
+
 ## [7.4.0] - 2026-06-22
 ### Changed
 - Renamed the base `IOClients` Janus Catalog getter from `catalogSystem` to

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "VTEX I/O API client",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

src/HttpClient/middlewares/request/setupAxios/__tests__/TestTracer.ts

@@ -30,4 +30,8 @@ export class TestTracer implements IUserLandTracer {
   public fallbackSpanContext() {
     return this.fallbackSpan.context()
   }
+
+  public setFallbackSpanTag(key: string, value: unknown): void {
+    this.fallbackSpan.setTag(key, value)
+  }
 }

src/tracing/Tags.ts

@@ -1,5 +1,5 @@
 import { Tags as OpentracingTags } from 'opentracing'
 export { OpentracingTags }
 
 /* tslint:disable:object-literal-sort-keys */
 
@@ -74,6 +74,11 @@
   HTTP_RETRY_COUNT = 'http.retry.count',
 }
 
+export const enum GraphQLTags {
+  GRAPHQL_OPERATION_NAME = 'graphql.operation.name',
+  GRAPHQL_OPERATION_TYPE = 'graphql.operation.type',
+}
+
 export const UserlandTags = {
   ...OpentracingTags,
 }

src/tracing/UserLandTracer.test.ts

@@ -0,0 +1,63 @@
+import { MockSpan, MockTracer } from '@tiagonapoli/opentracing-alternate-mock'
+
+import { GraphQLTags } from './Tags'
+import { UserLandTracer } from './UserLandTracer'
+
+describe('UserLandTracer.setFallbackSpanTag', () => {
+  test('writes a tag only to the fallback span', () => {
+    const tracer = new MockTracer()
+    const fallback = tracer.startSpan('incoming-request') as MockSpan
+    const userLandTracer = new UserLandTracer(tracer, fallback)
+
+    userLandTracer.setFallbackSpanTag(
+      GraphQLTags.GRAPHQL_OPERATION_NAME,
+      'GetProduct'
+    )
+    const child = userLandTracer.startSpan('child') as MockSpan
+
+    expect(fallback.tags()).toHaveProperty(
+      [GraphQLTags.GRAPHQL_OPERATION_NAME],
+      'GetProduct'
+    )
+    expect(child.tags()).not.toHaveProperty(
+      [GraphQLTags.GRAPHQL_OPERATION_NAME]
+    )
+  })
+
+  test('is a no-op when there is no fallback span', () => {
+    const userLandTracer = new UserLandTracer(new MockTracer())
+
+    expect(() => {
+      userLandTracer.setFallbackSpanTag(
+        GraphQLTags.GRAPHQL_OPERATION_TYPE,
+        'query'
+      )
+    }).not.toThrow()
+  })
+
+  test('can write after the fallback span is locked', () => {
+    const tracer = new MockTracer()
+    const fallback = tracer.startSpan('incoming-request') as MockSpan
+    const replacement = tracer.startSpan('replacement') as MockSpan
+    const userLandTracer = new UserLandTracer(tracer, fallback)
+
+    userLandTracer.lockFallbackSpan()
+
+    expect(() => userLandTracer.setFallbackSpan(replacement)).toThrow(
+      "FallbackSpan is locked, can't change it"
+    )
+    expect(() => {
+      userLandTracer.setFallbackSpanTag(
+        GraphQLTags.GRAPHQL_OPERATION_TYPE,
+        'query'
+      )
+    }).not.toThrow()
+    expect(fallback.tags()).toHaveProperty(
+      [GraphQLTags.GRAPHQL_OPERATION_TYPE],
+      'query'
+    )
+    expect(replacement.tags()).not.toHaveProperty(
+      [GraphQLTags.GRAPHQL_OPERATION_TYPE]
+    )
+  })
+})

src/tracing/UserLandTracer.ts

@@ -8,6 +8,7 @@
   startSpan: Tracer['startSpan']
   inject: Tracer['inject']
   fallbackSpanContext: () => SpanContext | undefined
+  setFallbackSpanTag: (key: string, value: unknown) => void
 }
 
 export const createTracingContextFromCarrier = (
@@ -27,14 +28,14 @@
 }
 
 export class UserLandTracer implements IUserLandTracer {
   private tracer: Tracer
   private fallbackSpan: Span | undefined
   private fallbackSpanLock: boolean
 
   // tslint:disable-next-line
   private _isSampled: boolean
   // tslint:disable-next-line
   private _traceId?: string
 
   constructor(tracer: Tracer, fallbackSpan?: Span) {
     this.tracer = tracer
@@ -81,4 +82,8 @@
   public fallbackSpanContext(): SpanContext | undefined {
     return this.fallbackSpan?.context()
   }
+
+  public setFallbackSpanTag(key: string, value: unknown): void {
+    this.fallbackSpan?.setTag(key, value)
+  }
 }

src/tracing/index.ts

@@ -4,7 +4,7 @@
 export { ErrorReport } from './errorReporting/ErrorReport'
 export { createSpanReference } from './spanReference/createSpanReference'
 export { SpanReferenceTypes } from './spanReference/SpanReferenceTypes'
-export { UserlandTags as TracingTags } from './Tags'
+export { UserlandTags as TracingTags, GraphQLTags } from './Tags'
 export { createTracingContextFromCarrier, IUserLandTracer } from './UserLandTracer'
 export { getTraceInfo, TraceInfo } from './utils'
 export { Span, FORMAT_HTTP_HEADERS }