@@ -196,9 +196,76 @@ context for an operation using any native object.
196196
197197## Utilities
198198
199- Tracing modules comes with certain utility method when you don't want to use attribute for capturing a code block
199+ Tracing modules comes with certain utility methods when you don't want to use attribute for capturing a code block
200200under a subsegment, or you are doing multithreaded programming. Refer examples below.
201201
202+ ### Using Statement Pattern
203+
204+ You can create subsegments using the familiar ` using ` statement pattern for automatic cleanup and exception safety.
205+
206+ === "Basic Using Statement"
207+
208+ ```c# hl_lines="8 9 10 11 12 13"
209+ using AWS.Lambda.Powertools.Tracing;
210+
211+ public class Function
212+ {
213+ public async Task<APIGatewayProxyResponse> FunctionHandler
214+ (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
215+ {
216+ using var gatewaySegment = Tracing.BeginSubsegment("PaymentGatewayIntegration");
217+ gatewaySegment.AddAnnotation("Operation", "ProcessPayment");
218+ gatewaySegment.AddAnnotation("PaymentMethod", "CreditCard");
219+
220+ var result = await ProcessPaymentAsync();
221+ gatewaySegment.AddAnnotation("ProcessingTimeMs", result.ProcessingTimeMs);
222+ // Subsegment automatically ends when disposed
223+ }
224+ }
225+ ```
226+
227+ === "With Custom Namespace"
228+
229+ ```c# hl_lines="8 9 10"
230+ using AWS.Lambda.Powertools.Tracing;
231+
232+ public class Function
233+ {
234+ public async Task<APIGatewayProxyResponse> FunctionHandler
235+ (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
236+ {
237+ using var segment = Tracing.BeginSubsegment("MyCustomNamespace", "DatabaseOperation");
238+ segment.AddAnnotation("TableName", "Users");
239+ segment.AddMetadata("query", "SELECT * FROM Users WHERE Active = 1");
240+ }
241+ }
242+ ```
243+
244+ === "Nested Subsegments"
245+
246+ ```c# hl_lines="8 9 10 11 12 13 14 15 16"
247+ using AWS.Lambda.Powertools.Tracing;
248+
249+ public class Function
250+ {
251+ public async Task<APIGatewayProxyResponse> FunctionHandler
252+ (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
253+ {
254+ using var outerSegment = Tracing.BeginSubsegment("PaymentProcessing");
255+ outerSegment.AddAnnotation("Operation", "ProcessPayment");
256+
257+ var result = await ProcessPaymentAsync();
258+
259+ using var postProcessingSegment = Tracing.BeginSubsegment("PaymentPostProcessing");
260+ postProcessingSegment.AddAnnotation("PaymentId", result.PaymentId);
261+
262+ await PostProcessPaymentAsync(result);
263+ }
264+ }
265+ ```
266+
267+ ### Callback Pattern
268+
202269=== "Functional Api"
203270
204271 ```c# hl_lines="8 9 10 12 13 14"
@@ -244,6 +311,31 @@ under a subsegment, or you are doing multithreaded programming. Refer examples b
244311 }
245312 ```
246313
314+ ### Subsegment Methods
315+
316+ When using the ` using ` statement pattern, the returned ` TracingSubsegment ` object provides direct access to tracing methods:
317+
318+ === "Available Methods"
319+
320+ ```c# hl_lines="8 9 10 11 12 13 14 15 16"
321+ using var segment = Tracing.BeginSubsegment("PaymentProcessing");
322+
323+ // Add annotations (indexed by X-Ray)
324+ segment.AddAnnotation("PaymentMethod", "CreditCard");
325+ segment.AddAnnotation("Amount", 99.99);
326+
327+ // Add metadata (not indexed, for additional context)
328+ segment.AddMetadata("PaymentDetails", paymentObject);
329+ segment.AddMetadata("CustomNamespace", "RequestId", requestId);
330+
331+ // Add exception information
332+ segment.AddException(exception);
333+
334+ // Add HTTP information
335+ segment.AddHttpInformation("response_code", 200);
336+ segment.AddHttpInformation("url", "https://api.payment.com/process");
337+ ```
338+
247339## Instrumenting SDK clients
248340
249341You should make sure to instrument the SDK clients explicitly based on the function dependency. You can instrument all of your AWS SDK for .NET clients by calling RegisterForAllServices before you create them.
0 commit comments