feat: gcp pubsub admin endpoints by ojproductions · Pull Request #4957 · DataDog/dd-trace-go

ojproductions · 2026-06-25T14:46:40Z

What does this PR do?

Implements instrumentation for admin endpoints across v1 and v2 listed in the tables below

Common Span Tags (All Admin Operations)

All admin operations are traced via TraceAdmin in contrib/cloud.google.com/go/pubsubtrace/tracing.go and share these tags:

Tag	Value	Notes
`span.type`	`worker`	`ext.SpanTypeWorker`
`span.kind`	`client`	`ext.SpanKindClient`
`messaging.system`	`googlepubsub`	`ext.MessagingSystemGCPPubsub`
`component`	Package name	`cloud.google.com/go/pubsub` (v1) or `cloud.google.com/go/pubsub/v2` (v2)
`pubsub.method`	Operation name	e.g. `"CreateTopic"`, `"DeleteSubscription"`
`resource.name`	`"<method> <resourcePath>"`	Falls back to just `<method>` if path is empty
`gcloud.project_id`	Extracted from resource path	Only set when path starts with `"projects/"`
Measured	`true`	Always measured — not configurable via `WithMeasured()`
Span name	`requestSpanName`	Derived from `instr.OperationName(ComponentClient, nil)`

V1 vs V2 Client Type Mapping

Operation Category	V1 Client	V2 Client
Topic operations	`PublisherClient` (`cloud.google.com/go/pubsub/apiv1`)	`TopicAdminClient` (`cloud.google.com/go/pubsub/v2/apiv1`)
Subscription + snapshot operations	`SubscriberClient` (`cloud.google.com/go/pubsub/apiv1`)	`SubscriptionAdminClient` (`cloud.google.com/go/pubsub/v2/apiv1`)
Schema operations	`SchemaClient` (`cloud.google.com/go/pubsub/apiv1`)	`SchemaClient` (`cloud.google.com/go/pubsub/v2/apiv1`)

Topic Operations

Operation	`pubsub.method`	Resource path source	`gcloud.project_id` set?	V1 tracer helper	V2 tracer helper
`CreateTopic`	`"CreateTopic"`	`req.GetName()`	Yes (topic path)	`TraceCreateTopicV1`	`TraceCreateTopic`
`UpdateTopic`	`"UpdateTopic"`	`req.GetTopic().GetName()`	Yes (topic path)	`TraceUpdateTopicV1`	`TraceUpdateTopic`
`GetTopic`	`"GetTopic"`	`req.GetTopic()`	Yes (topic path)	`TraceGetTopicV1`	`TraceGetTopic`
`ListTopics`	`"ListTopics"`	`req.GetProject()`	Yes (`"projects/..."`)	`TraceListTopicsV1`	`TraceListTopics`
`ListTopicSubscriptions`	`"ListTopicSubscriptions"`	`req.GetTopic()`	Yes (topic path)	`TraceListTopicSubscriptionsV1`	`TraceListTopicSubscriptions`
`ListTopicSnapshots`	`"ListTopicSnapshots"`	`req.GetTopic()`	Yes (topic path)	`TraceListTopicSnapshotsV1`	`TraceListTopicSnapshots`
`DeleteTopic`	`"DeleteTopic"`	`req.GetTopic()`	Yes (topic path)	`TraceDeleteTopicV1`	`TraceDeleteTopic`
`DetachSubscription`	`"DetachSubscription"`	`req.GetSubscription()`	Yes (subscription path)	`TraceDetachSubscriptionV1`	`TraceDetachSubscription`

Subscription Operations

Operation	`pubsub.method`	Resource path source	`gcloud.project_id` set?	V1 tracer helper	V2 tracer helper
`CreateSubscription`	`"CreateSubscription"`	`req.GetName()`	Yes (sub path)	`TraceCreateSubscriptionV1`	`TraceCreateSubscription`
`GetSubscription`	`"GetSubscription"`	`req.GetSubscription()`	Yes (sub path)	`TraceGetSubscriptionV1`	`TraceGetSubscription`
`UpdateSubscription`	`"UpdateSubscription"`	`req.GetSubscription().GetName()`	Yes (sub path)	`TraceUpdateSubscriptionV1`	`TraceUpdateSubscription`
`ListSubscriptions`	`"ListSubscriptions"`	`req.GetProject()`	Yes (`"projects/..."`)	`TraceListSubscriptionsV1`	`TraceListSubscriptions`
`DeleteSubscription`	`"DeleteSubscription"`	`req.GetSubscription()`	Yes (sub path)	`TraceDeleteSubscriptionV1`	`TraceDeleteSubscription`
`ModifyPushConfig`	`"ModifyPushConfig"`	`req.GetSubscription()`	Yes (sub path)	`TraceModifyPushConfigV1`	`TraceModifyPushConfig`
`Seek`	`"Seek"`	`req.GetSubscription()`	Yes (sub path)	`TraceSeekV1`	`TraceSeek`

Snapshot Operations

Operation	`pubsub.method`	Resource path source	`gcloud.project_id` set?	V1 tracer helper	V2 tracer helper
`GetSnapshot`	`"GetSnapshot"`	`req.GetSnapshot()`	Yes (snapshot path)	`TraceGetSnapshotV1`	`TraceGetSnapshot`
`ListSnapshots`	`"ListSnapshots"`	`req.GetProject()`	Yes (`"projects/..."`)	`TraceListSnapshotsV1`	`TraceListSnapshots`
`CreateSnapshot`	`"CreateSnapshot"`	`req.GetName()`	Yes (snapshot path)	`TraceCreateSnapshotV1`	`TraceCreateSnapshot`
`UpdateSnapshot`	`"UpdateSnapshot"`	`req.GetSnapshot().GetName()`	Yes (snapshot path)	`TraceUpdateSnapshotV1`	`TraceUpdateSnapshot`
`DeleteSnapshot`	`"DeleteSnapshot"`	`req.GetSnapshot()`	Yes (snapshot path)	`TraceDeleteSnapshotV1`	`TraceDeleteSnapshot`

Schema Operations

Operation	`pubsub.method`	Resource path source	`gcloud.project_id` set?	V1 tracer helper	V2 tracer helper
`CreateSchema`	`"CreateSchema"`	`req.GetParent()`	Yes (`"projects/..."`)	`TraceCreateSchemaV1`	`TraceCreateSchema`
`GetSchema`	`"GetSchema"`	`req.GetName()`	Yes (schema path)	`TraceGetSchemaV1`	`TraceGetSchema`
`ListSchemas`	`"ListSchemas"`	`req.GetParent()`	Yes (`"projects/..."`)	`TraceListSchemasV1`	`TraceListSchemas`
`ListSchemaRevisions`	`"ListSchemaRevisions"`	`req.GetName()`	Yes (schema path)	`TraceListSchemaRevisionsV1`	`TraceListSchemaRevisions`
`CommitSchema`	`"CommitSchema"`	`req.GetName()`	Yes (schema path)	`TraceCommitSchemaV1`	`TraceCommitSchema`
`RollbackSchema`	`"RollbackSchema"`	`req.GetName()`	Yes (schema path)	`TraceRollbackSchemaV1`	`TraceRollbackSchema`
`DeleteSchemaRevision`	`"DeleteSchemaRevision"`	`req.GetName()`	Yes (schema path)	`TraceDeleteSchemaRevisionV1`	`TraceDeleteSchemaRevision`
`DeleteSchema`	`"DeleteSchema"`	`req.GetName()`	Yes (schema path)	`TraceDeleteSchemaV1`	`TraceDeleteSchema`
`ValidateSchema`	`"ValidateSchema"`	`req.GetParent()`	Yes (`"projects/..."`)	`TraceValidateSchemaV1`	`TraceValidateSchema`
`ValidateMessage`	`"ValidateMessage"`	`req.GetParent()`	Yes (`"projects/..."`)	`TraceValidateMessageV1`	`TraceValidateMessage`

Motivation

APMSVLS-536
view @pablomartinezbernardo's python implementation here

Questions:
Should we be instrumenting v1? Its being deprecated by google

Reviewer's Checklist

Changed code has unit tests for its functionality at or near 100% coverage.
System-Tests covering this feature have been added and enabled with the va.b.c-dev version tag.
There is a benchmark for any new code, or changes to existing code.
If this interacts with the agent in a new way, a system test has been added.
New code is free of linting errors. You can check this by running make lint locally.
New code doesn't break existing tests. You can check this by running make test locally.
Add an appropriate team label so this PR gets put in the right place for the release notes.
All generated files are up to date. You can check this by running make generate locally.
Non-trivial go.mod changes, e.g. adding new modules, are reviewed by @DataDog/dd-trace-go-guild. Make sure all nested modules are up to date by running make fix-modules locally.

Unsure? Have a question? Request a review!

…pubsub-admin-endpoints

datadog-datadog-prod-us1-2 · 2026-06-25T14:47:06Z

Tests

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 2 Pipeline jobs failed

Static Checks | check-modules

Check Pull Request CI Status | all-jobs-are-green

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 18.07%
• Overall Coverage: 62.49% (-0.27%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: fb1c555 | Docs | Datadog PR Page | Give us feedback!}

…pubsub-admin-endpoints

pr-commenter · 2026-06-25T15:22:11Z

Benchmarks

Benchmark execution time: 2026-06-26 15:49:42

Comparing candidate commit fb1c555 in PR branch onzia/gcp-pubsub-admin-endpoints with baseline commit 712b634 in branch onzia/gcp-pubsub-span-links.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 297 metrics, 2 unstable metrics, 1 flaky benchmarks without significant changes.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

🟩 = significantly better candidate vs. baseline
🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

Known flaky benchmarks

These benchmarks are marked as flaky and will not trigger a failure. Modify FLAKY_BENCHMARKS_REGEX to control which benchmarks are marked as flaky.

Known flaky benchmarks without significant changes:

scenario:BenchmarkOTLPTraceWriterFlush

…n-endpoints

ojproductions · 2026-06-25T16:26:14Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c0147bb7f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-25T16:33:00Z

+func (c *TopicAdminClient) ListTopics(ctx context.Context, req *pubsubpb.ListTopicsRequest, opts ...gax.CallOption) *vkit.TopicIterator {
+	ctx, finish := pstrace.TraceListTopics(ctx, req, c.opts...)
+	it := c.TopicAdminClient.ListTopics(ctx, req, opts...)
+	finish(nil)


Defer finishing list spans until iteration

When callers use any of the List* admin methods, the Pub/Sub GAPIC returns an iterator and reports RPC errors when the iterator is consumed via Next/All, not from this method call. Finishing the span here with nil before returning means auth, deadline, or service errors during listing, as well as the actual RPC latency, are recorded as a successful near-zero span; the same pattern appears in the other List* wrappers/aspects, so those spans need to be closed from the iterator path instead.

Useful? React with 👍 / 👎.

…n-endpoints

rarguelloF · 2026-07-08T07:45:05Z

+  # implemented on the GAPIC clients in cloud.google.com/go/pubsub/v2/apiv1. A package-level
+  # tracer is injected into that package and each management method is wrapped to emit a
+  # gcp.pubsub.request span.
+  - id: Initialize pubsubtrace (admin)


these orchestrion aspects should have comprehensive tests inside internal/orchestrion/_integration trying to cover all the different patterns this library can be used.

rarguelloF · 2026-07-08T07:46:19Z

+	// SpanTypeWorker marks a span as a worker/management operation, such as a
+	// Pub/Sub admin (topic, subscription, snapshot, schema management) request.
+	SpanTypeWorker = "worker"


is this the only usage we intend for this new span type? or do we intend to change all the existing worker kind of spans to this new type?

rarguelloF · 2026-07-08T08:01:28Z

+// management operations. It embeds the wrapped client, so any method that is not traced
+// (e.g. Publish, IAM helpers, Close) is forwarded to the underlying client unchanged.
+type TopicAdminClient struct {
+	*vkit.TopicAdminClient


it seems this client supports adding grpc interceptors, so could we instead of wrapping, implementing tracing for this client via a grpc unary interceptor? This would make this more simple, specially on the orchestrion side of things.

You can add the new interceptor with:

client, err := apiv1.NewTopicAdminClient(ctx, option.WithGRPCDialOption( grpc.WithChainUnaryInterceptor(tracingInterceptor), ), )

ojproductions added 5 commits June 17, 2026 11:36

instrument admin endpoints

9f655ad

Merge branch 'main' of github.com:DataDog/dd-trace-go into onzia/gcp-…

8ac068c

…pubsub-admin-endpoints

Merge branch 'main' of github.com:DataDog/dd-trace-go into onzia/gcp-…

7fed46f

…pubsub-admin-endpoints

comments

cc1c3fd

implement v1

ae5ddaf

github-actions Bot added the apm:ecosystem contrib/* related feature requests or bugs label Jun 25, 2026

ojproductions changed the base branch from main to onzia/gcp-pubsub-span-links June 25, 2026 14:50

Merge branch 'main' of github.com:DataDog/dd-trace-go into onzia/gcp-…

71fbbf9

…pubsub-admin-endpoints

ojproductions changed the title ~~Onzia/gcp pubsub admin endpoints~~ feat: gcp pubsub admin endpoints Jun 25, 2026

Merge branch 'onzia/gcp-pubsub-span-links' into onzia/gcp-pubsub-admi…

3c0147b

…n-endpoints

ojproductions marked this pull request as ready for review June 25, 2026 16:27

ojproductions requested review from a team as code owners June 25, 2026 16:27

ojproductions requested review from rarguelloF and removed request for a team June 25, 2026 16:27

chatgpt-codex-connector Bot reviewed Jun 25, 2026

View reviewed changes

Merge branch 'onzia/gcp-pubsub-span-links' into onzia/gcp-pubsub-admi…

726ae46

…n-endpoints

darccio self-assigned this Jun 26, 2026

Merge branch 'onzia/gcp-pubsub-span-links' into onzia/gcp-pubsub-admi…

fb1c555

…n-endpoints

rarguelloF requested changes Jul 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: gcp pubsub admin endpoints#4957

feat: gcp pubsub admin endpoints#4957
ojproductions wants to merge 9 commits into
onzia/gcp-pubsub-span-linksfrom
onzia/gcp-pubsub-admin-endpoints

ojproductions commented Jun 25, 2026 •

edited

Loading

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Jun 25, 2026 •

edited

Loading

Uh oh!

pr-commenter Bot commented Jun 25, 2026 •

edited

Loading

Explanation

More details about the CI and significant changes

Known flaky benchmarks

Uh oh!

ojproductions commented Jun 25, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 25, 2026

Uh oh!

rarguelloF Jul 8, 2026

Uh oh!

rarguelloF Jul 8, 2026

Uh oh!

rarguelloF Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

What does this PR do?

Common Span Tags (All Admin Operations)

V1 vs V2 Client Type Mapping

Topic Operations

Subscription Operations

Snapshot Operations

Schema Operations

Motivation

Reviewer's Checklist

Uh oh!

datadog-datadog-prod-us1-2 Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

ℹ️ Info

Uh oh!

pr-commenter Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks

Explanation

More details about the CI and significant changes

Known flaky benchmarks

Uh oh!

ojproductions commented Jun 25, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

rarguelloF Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rarguelloF Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rarguelloF Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ojproductions commented Jun 25, 2026 •

edited

Loading

datadog-datadog-prod-us1-2 Bot commented Jun 25, 2026 •

edited

Loading

pr-commenter Bot commented Jun 25, 2026 •

edited

Loading