Merge pull request #5555 from santiagxf/santiagxf-patch-1

Update trace-application.md

Author: prmerger-automator[bot]

articles/ai-foundry/how-to/develop/trace-application.md

@@ -15,7 +15,7 @@ ms.topic: how-to
 
 Tracing provides deep visibility into execution of your application by capturing detailed telemetry at each execution step. Such helps diagnose issues and enhance performance by identifying problems such as inaccurate tool calls, misleading prompts, high latency, low-quality evaluation scores, and more.  
 
-This article explains how to implement tracing for AI applications using OpenAI SDK with OpenTelemetry in Azure AI Foundry.
+This article explains how to implement tracing for AI applications using **OpenAI SDK** with OpenTelemetry in Azure AI Foundry.
 
 ## Prerequisites
 
@@ -28,9 +28,9 @@ You need the following to complete this tutorial:
 
 ## Enable tracing in your project
 
-Azure AI Foundry stores traces in Azure Application Insight resources using OpenTelemetry. By default, new Azure AI Foundry resources don't provision these resources. You can connect them to an existing Azure Application Insights resource or create a new one from within the project. You do such configuration once per each Azure AI Foundry resource.
+Azure AI Foundry stores traces in Azure Application Insight resources using OpenTelemetry. By default, new Azure AI Foundry resources don't provision these resources. You can connect projects to an existing Azure Application Insights resource or create a new one from within the project. You do such configuration once per each Azure AI Foundry resource.
 
-The following steps show how to configure:
+The following steps show how to configure your resource:
 
 1. Go to [Azure AI Foundry portal](https://ai.azure.com) and navigate to your project.
 
@@ -56,7 +56,7 @@ The following steps show how to configure:
 
     3. Select **Create** to create the resource and connect it to the Azure AI Foundry resource.
 
-4. Once the connection is configured, you are ready to use tracing in this project.
+4. Once the connection is configured, you are ready to use tracing in any project within the resource.
 
 5. Go to the landing page of your project and copy the project's endpoint URI. You need it later in the tutorial.
 
@@ -68,7 +68,7 @@ The following steps show how to configure:
 
 ## Instrument the OpenAI SDK
 
-When developing using the OpenAI SDK you can instrument your code so traces are sent to Azure AI Foundry. Follow these steps:
+When developing with the OpenAI SDK, you can instrument your code so traces are sent to Azure AI Foundry. Follow these steps to instrument your code:
 
 1. Install `azure-ai-projects`, `azure-monitor-opentelemetry`, and `opentelemetry-instrumentation-openai-v2` in your environment. The following example uses `pip`:
 
@@ -84,7 +84,7 @@ When developing using the OpenAI SDK you can instrument your code so traces are
     OpenAIInstrumentor().instrument()
     ```
 
-1. Get the connection string to the Azure Application Insights resource to your project:
+1. Get the connection string to the Azure Application Insights resource associated with your project:
 
     ```python
     from azure.ai.projects import AIProjectClient
@@ -103,17 +103,17 @@ When developing using the OpenAI SDK you can instrument your code so traces are
     >
     > :::image type="content" source="../../media/how-to/develop/trace-application/tracing-copy-connection-string.png" alt-text="A screenshot showing how to copy the connection string to the underlying Azure Application Insights resource from a project." lightbox="../../media/how-to/develop/trace-application/tracing-copy-connection-string.png":::
 
-1. Configure OpenTelemetry to send traces to the Azure Application Insights used by Azure AI Foundry:
+1. Configure OpenTelemetry to send traces to the Azure Application Insights:
 
     ```python
     from azure.monitor.opentelemetry import configure_azure_monitor
 
     configure_azure_monitor(connection_string=connection_string)
     ```
 
-1. By default, OpenTelemetry doesn't capture inputs and outputs. Use the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` to capture it. Ensure this environment variable is configured in the environment level where your code is running.
+1. By default, OpenTelemetry doesn't capture inputs and outputs. Use the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` to capture them. Ensure this environment variable is configured in the environment level where your code is running.
 
-1. Use the OpenAI SDK in the same way you are used to:
+1. Use the OpenAI SDK as usual:
 
     ```python
     client = project_client.get_azure_openai_client()
@@ -130,15 +130,15 @@ When developing using the OpenAI SDK you can instrument your code so traces are
 
     :::image type="content" source="../../media/how-to/develop/trace-application/tracing-display-simple.png" alt-text="A screenshot showing how a simple chat completion request is displayed in the trace." lightbox="../../media/how-to/develop/trace-application/tracing-display-simple.png":::
 
-1. It may be useful to capture sections of your code that mixes business logic with models when developing complex applications. You can do that by first getting an instance of the current tracer.
+1. It may be useful to capture sections of your code that mixes business logic with models when developing complex applications. OpenTelemetry uses the concept of spans to capture sections you're interested in. To start generating your own spans, get an instance of the current **tracer** object.
 
     ```python
     from opentelemetry import trace
 
     tracer = trace.get_tracer(__name__)
     ```
 
-1. Then, use decorators in your method to capture specific scenarios in your code that you are interested in. The following example assesses if a list of claims with a list of contexts.
+1. Then, use decorators in your method to capture specific scenarios in your code that you are interested in. Such decorators generate spans automatically. The following code example instruments a method called `assess_claims_with_context` with iterates over a list of claims and verify if the claim is supported by the context using an LLM. All the calls made in this method are captured within the same span:
 
     ```python
     def build_prompt_with_context(claim: str, context: str) -> str:
@@ -171,7 +171,7 @@ When developing using the OpenAI SDK you can instrument your code so traces are
 
     :::image type="content" source="../../media/how-to/develop/trace-application/tracing-display-decorator.png" alt-text="A screenshot showing how a method using a decorator is displayed in the trace." lightbox="../../media/how-to/develop/trace-application/tracing-display-decorator.png":::
 
-1. You may also want to add extra information as attributes to the current span. Use the `trace` object to access it and include extra information. See how the `assess_claims_with_context` method has been modified to include an attribute:
+1. You may also want to add extra information to the current span. OpenTelemetry uses the concept of **attributes** for that. Use the `trace` object to access them and include extra information. See how the `assess_claims_with_context` method has been modified to include an attribute:
 
     ```python
     @tracer.start_as_current_span("assess_claims_with_context")
@@ -274,4 +274,4 @@ Configure tracing as follows:
 
 ## Next steps
 
-* [Trace agents using Azure AI Foundry SDK](trace-agents-sdk.md)
+* [Trace agents using Azure AI Foundry SDK](trace-agents-sdk.md)