Azure / Azure/azure-sdk-for-python
[azure-ai-projects] Client trace instrumentation lacks Foundry project identity
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 193
Description
- **Package Name**: `azure-ai-projects`
- **Package Version**: `2.3.0`
- **Operating System**: Windows 11 Enterprise 10.0.26200
- **Python Version**: 3.13.15
**Describe the bug**
Client-side `invoke_agent` spans created through the documented `AIProjectInstrumentor` and Azure Monitor path do not include `microsoft.foundry.project.id`. The spans reach the Application Insights resource connected to the Foundry project and include `gen_ai.response.id`, but they are not discoverable in that agent's Foundry **Traces** view.
`AIProjectClient` exposes the project endpoint but no public project ARM resource ID. The endpoint contains the account and project names, but not the subscription ID or resource group needed to construct the full ARM ID. `AIProjectInstrumentor.instrument()` also has no project identity option and does not enrich its spans with this attribute.
The current workaround is to list project connections and derive the parent project resource ID from `Connection.id`:
```python
connection = next(iter(project_client.connections.list()), None)
project_arm_id = connection.id.rsplit("/connections/", 1)[0] if connection else None
```
This pattern also appears in the repository's human-evaluations sample, but it is not documented for client tracing and requires an extra service call plus resource-ID parsing.
**To Reproduce**
Steps to reproduce the behavior:
1. Create or use a Foundry project with Application Insights connected and a published Prompt Agent.
2. Set `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_AGENT_NAME`, and `FOUNDRY_AGENT_VERSION`.
3. Run:
```python
import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.telemetry import AIProjectInstrumentor
from azure.identity import DefaultAzureCredential
from azure.monitor.opentelemetry import configure_azure_monitor
os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"
AIProjectInstrumentor().instrument()
with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
) as project_client,
):
configure_azure_monitor(
connection_string=project_client.telemetry.get_application_insights_connection_string(),
enable_live_metrics=False,
)
openai_client = project_client.get_openai_client()
openai_client.responses.create(
input="Reply with exactly OK.",
extra_body={
"agent_reference": {
"name": os.environ["FOUNDRY_AGENT_NAME"],
"version": os.environ["FOUNDRY_AGENT_VERSION"],
"type": "agent_reference",
}
},
)
```
4. Inspect the resulting `invoke_agent` dependency in the connected Application Insights resource. It has the agent/response attributes, but not `microsoft.foundry.project.id`.
5. Open the published agent's **Traces** view in Foundry. The client-side trace is not listed.
6. Add the full project ARM ID as `microsoft.foundry.project.id` to the root `invoke_agent` span and repeat. The client-side trace is listed.
This was also reproduced through Microsoft Agent Framework and isolated with controlled live traces in microsoft/agent-framework#7492.
**Expected behavior**
The supported `azure-ai-projects` client-tracing setup should provide a public, documented way to associate client spans with the current Foundry project so they appear in the project's Foundry **Traces** view.
Possible SDK-level solutions include:
- Expose the project's ARM resource ID directly from `AIProjectClient`.
- Add a telemetry operation that returns project identity together with the Application Insights connection information.
- Allow `AIProjectInstrumentor.instrument(project_arm_id=...)` and use it to enrich generated `invoke_agent` spans.
- Automatically resolve and cache project identity inside the instrumentor.
Consumers should not need to parse a child connection resource ID to obtain project identity.
**Screenshots**
The original Agent Framework report contains Foundry and Application Insights screenshots demonstrating the missing client trace: microsoft/agent-framework#7492.
**Additional context**
- `AIProjectInstrumentor.instrument()` currently accepts `enable_content_recording`, `enable_trace_context_propagation`, and `enable_baggage_propagation`, but no project identity.
- The official human-evaluations sample derives `project_resource_id` from `Connection.id`: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/evaluations/sample_human_evaluations.py
- Foundry-hosted agentserver code receives `FOUNDRY_PROJECT_ARM_ID` from the platform and emits `microsoft.foundry.project.id`, but external client applications do not receive that environment variable automatically.
- This report is specifically about Foundry trace-list discovery. HTTPX/W3C trace-context propagation is tracked separately by Azure/azure-sdk-for-python#46286 and Azure/azure-sdk-for-python#47953.
Contributor guide
Assessment
This issue has not been assessed yet.