Add generate-method-instrumentation flag to enable ActivitySource-based distributed tracing in client convenience methods

[Copilot]

Adds first-class support for ActivitySource-based distributed tracing in generated client convenience methods, enabled by default via the generate-method-instrumentation flag.

Changes Made

• options.ts: Added generate-method-instrumentation option to TypeScript emitter options
• Configuration.cs: Added GenerateMethodInstrumentation property (defaults to true)
• ClientProvider.cs: Added ActivitySource static field to all clients (root and sub-clients) when instrumentation is enabled
• ScmMethodProviderCollection.cs: Added distributed tracing to convenience methods:
  • Non-paging methods: using Activity activity = _activitySource.StartActivity(...) wraps the HTTP call in a try-catch that calls activity?.SetStatus(ActivityStatusCode.Error, ex.Message) on exception before rethrowing — matching the Azure SDK pattern
  • Paging methods: pass _activitySource to the CollectionResultDefinition; no activity is started in the convenience method itself
• CollectionResultDefinition.cs: Stores ActivitySource? (instead of a single Activity?) and adds a private ExecutePageRequest/ExecutePageRequestAsync helper method. Each page HTTP request starts its own activity via this helper, which wraps the pipeline call in a try-catch with activity?.SetStatus(ActivityStatusCode.Error, ex.Message) on failure — matching the Azure DevCenter per-page tracing pattern. This avoids the CS1626 restriction (no yield return inside try-catch) since the helper is a non-iterator method.
• MockHelpers.cs: Added enableMethodInstrumentation parameter and disabled instrumentation by default in tests (via Configuration.json) to avoid updating all existing test snapshots
• Tests: Added 5 new tests in ScmMethodProviderCollectionTests.cs validating tracing for regular client methods, sub-client methods, and paging methods (including per-page activity start/stop in ExecutePageRequest and try-catch with SetStatus)
• Generated test files: Regenerated Local Sample-TypeSpec test project — all convenience methods updated with the try-catch exception tracking pattern; sub-client files updated with _activitySource field; collection result classes updated with _activitySource field and ExecutePageRequest helper; paging convenience methods updated to pass _activitySource to the collection

Testing

• ✅ All 1175 tests pass

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add flag to enable client method instrumentation</issue_title>
<issue_description>See Azure/azure-sdk-for-net#55575. Initially attempted to do this as a visitor for the Azure on SCM libraries, but that doesn't really make sense since we can't reuse the Azure visitor. We should probably add first-class support for this and have it enabled by default. In the Azure emitter, we would turn off the instrumentation, but for libraries doing Azure on SCM it would be turned on. </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add flag to enable client method instrumentation #9914

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[JoshLove-msft]

@copilot run the Generate.ps1 script

[JoshLove-msft]

@copilot we need to add tests that validate the tracing is added for client methods and for subclient methods. We should also update the paging methods to support tracing.

[Copilot]

Done in 1853adb. Here's what was implemented:

Tests added (ScmMethodProviderCollectionTests.cs):

• TracingIsAddedToConvenienceMethod — verifies using Activity is prepended to regular convenience methods
• TracingIsNotAddedToConvenienceMethodWhenDisabled — verifies no tracing when disabled
• TracingIsAddedToSubClientConvenienceMethod — verifies sub-clients also get tracing
• TracingIsAddedToPagingConvenienceMethod — verifies paging methods declare activity (without using)
• TracingInPagingCollectionDisposesActivityViaFinally — verifies the CollectionResultDefinition has _activity field, accepts it in the constructor, and disposes it via try-finally in GetRawPages

Sub-client fix (ClientProvider.cs): Removed ClientOptions != null check from ActivitySourceField — sub-clients now get their own _activitySource field.

Paging fix (CollectionResultDefinition.cs, ScmMethodProviderCollection.cs): Paging convenience methods now declare Activity activity = ... (no using) and pass it to the CollectionResultDefinition constructor. The collection stores the activity in _activity and disposes it in a try-finally block in GetRawPages/GetRawPagesAsync, so the activity spans the actual HTTP calls rather than just the instantiation.

[Copilot]

@copilot run the Generate.ps1 script

Done in 7b53cd0. Generate.ps1 ran successfully — all 73 test project Configuration.json files were updated with "generate-method-instrumentation": true, and SampleTypeSpecClient.cs was regenerated with the ActivitySource field and activity statements in convenience methods.

[JoshLove-msft]

@copilot is this all we need? We don't need a call for tracking exceptions like we have in Azure?

https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/src/Generated/EventGridReceiverClient.cs#L266-L276

[Copilot]

The current implementation doesn't track exceptions. When an exception is thrown, the using Activity statement disposes the activity, but no error status is recorded on the span — so failed operations appear indistinguishable from successful ones in tracing backends.

The Azure pattern's scope.Failed(e) marks the span with an error status and message. The equivalent for ActivitySource would be:

using Activity activity = _activitySource.StartActivity("...", ActivityKind.Client);
try
{
    return this.Method(options);
}
catch (Exception ex)
{
    activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
    throw;
}

For SCM clients, whether to add this depends on how useful error detection in traces is for users. If we want spans to accurately reflect failures (which I'd recommend), I can add the try-catch with SetStatus. Otherwise the current simpler approach just captures timing. Let me know if you'd like me to add it.

[JoshLove-msft]

@copilot please match the Azure pattern.

[Copilot]

Done in f719be4. Non-paging convenience methods now match the Azure pattern:

using Activity activity = _activitySource.StartActivity("SampleTypeSpecClient.SayHi", ActivityKind.Client);
try
{
    ClientResult result = SayHi(headParameter, queryParameter, optionalQuery, cancellationToken.ToRequestOptions());
    return ClientResult.FromValue((Thing)result, result.GetRawResponse());
}
catch (Exception ex)
{
    activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
    throw;
}

Note on paging methods: The GetRawPages iterator methods can only use try-finally (not try-catch). C# CS1626 prohibits yield return inside a try block that has a catch clause, so exception status tracking isn't possible in the iterator body. The activity is still disposed via the finally block when enumeration completes (successfully or with exception).

[Copilot]

@copilot run the Generate.ps1 script

I tried running Generate.ps1 but it fails in this environment due to a .NET SDK version mismatch (global.json requires 10.0.103, but only 10.0.102 is installed). I ran the generation manually for all affected projects:

• Local/Sample-TypeSpec: regenerated and committed in 1853adb with all the new paging and sub-client tracing changes
• Spector stubs: verified by running tsp compile on pageable — no files change. The StubLibraryVisitor strips private fields (so _activitySource never appears in stubs) and replaces all method bodies with throw null (so activity statements are stripped too). The CollectionResultDefinition is also internal so it's excluded from stubs entirely.

The generated files are therefore up to date — Spector stubs wouldn't show any of the instrumentation changes even if regenerated.

[JoshLove-msft]

@copilot we need to actually start the activity for each request. The pattern should mirror Azure - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/devcenter/Azure.Developer.DevCenter/src/Generated/CollectionResults/DeploymentEnvironmentsClientGetAllEnvironmentsCollectionResultOfT.cs#L64-L74

[JoshLove-msft]

We might need to add a parameter to the CollectionResultDefinition for the scope name.

[Copilot]

Done in 480bfbe. The pattern now mirrors Azure: each page request starts its own activity via a private ExecutePageRequest/ExecutePageRequestAsync helper on the collection result class.

The helper wraps the HTTP call with:

using Activity activity = _activitySource?.StartActivity("SampleTypeSpecClient.GetWithContinuationToken", ActivityKind.Client);
try
{
    return ClientResult.FromResponse(_client.Pipeline.ProcessMessage(message, _options));
}
catch (Exception ex)
{
    activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
    throw;
}

The collection stores ActivitySource? (passed from the convenience method) instead of a single Activity?. GetRawPages calls ExecutePageRequest(message) for each page, which starts/stops an activity per HTTP request. This avoids the CS1626 limitation (no yield return in try-catch) since the helper is a non-iterator method.

[Copilot]

@copilot run the Generate.ps1 script

Done in 480bfbe. The generator ran successfully and all 20 collection result files in Sample-TypeSpec have been regenerated with the new per-page activity pattern (ExecutePageRequest helper method). The convenience methods now pass _activitySource to the collection constructor instead of a pre-started activity.