docs: add guide for integrating SDK with existing OpenTelemetry

[juliomenendez]

Companion to microsoft/Agent365-Samples#288 (greenfield samples).

This PR adds a top-level documentation guide that explains how to integrate the Agent 365 SDK into an application that already has OpenTelemetry configured. It covers:

• Recommended initialization order (user's TracerProvider → configure() → framework instrumentor)
• Two minimal patterns: Azure Monitor and manual OTel SDK
• Auto vs manual instrumentation matrix
• Expected span types and their gen_ai.operation.name values
• Verification recipe for confirming traces arrive
• Common pitfalls (double-init, missing env var, casing discrepancy)
• Exporter-combination table

Also adds a short callout at the top of the observability-core README linking to the new guide.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Adds a new top-level guide documenting how to integrate microsoft-agents-a365-observability-core into applications that already initialize OpenTelemetry, and links to it from the observability-core README.

Changes:

• Add docs/integrating-with-existing-opentelemetry.md with recommended init order, minimal patterns, span expectations, verification steps, and pitfalls.
• Add a README callout in libraries/microsoft-agents-a365-observability-core/README.md pointing to the new integration guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
libraries/microsoft-agents-a365-observability-core/README.md	Adds a callout + link to the new “existing OTel integration” guide.
docs/integrating-with-existing-opentelemetry.md	Introduces the detailed integration guide, examples, and troubleshooting notes.

Comments suppressed due to low confidence (3)

docs/integrating-with-existing-opentelemetry.md:39

• The Pattern B snippet later references os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] but the import list doesn’t include import os, so the example isn’t runnable as-is. Add import os to the snippet imports.

```python
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

docs/integrating-with-existing-opentelemetry.md:86

• This table also uses || at the start of rows, which typically creates an unintended blank first column in Markdown. Switching to a single leading | per row will render the table correctly.

| `gen_ai.operation.name` | Produced by                                       | Typical parent | Span name (default) | Notes |
|-------------------------|---------------------------------------------------|----------------|---------------------|-------|
| `invoke_agent`          | `InvokeAgentScope` (one per user turn)            | (root or app)  | `invoke_agent <agent_name>` when set, else `invoke_agent` | |
| (varies — see notes) | `InferenceScope` (one per LLM call) | `invoke_agent` | `<operation> <model>` | **Manual instrumentation** uses `InferenceOperationType.value` (currently `Chat` / `TextCompletion` / `GenerateContent`, capitalized). **Auto-instrumentation** (e.g. `OpenAIAgentsTraceInstrumentor`) uses lowercase per the [OTel GenAI semconv](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) (e.g. `chat`). The two are inconsistent today. |
| `execute_tool`          | `ExecuteToolScope` (one per tool invocation)      | `invoke_agent` | `execute_tool <tool_name>` when set, else `execute_tool` | Records tool name, args, and result. |

docs/integrating-with-existing-opentelemetry.md:144

• The exporter combinations table rows also start with ||, which typically renders as an extra blank first column. Consider changing these rows to begin with a single | for consistent Markdown table rendering.

| Combination                             | What's installed                                                          | What to call                                                              | Gotchas                                                                                       |
|-----------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| Azure Monitor only                      | `azure-monitor-opentelemetry`                                             | `configure_azure_monitor(...)`                                            | Standard Azure Monitor — no Agent 365 spans flow.                                             |
| Azure Monitor + Agent 365               | `azure-monitor-opentelemetry`, `microsoft-agents-a365-observability-core` | `configure_azure_monitor(...)` then `configure(...)`                      | Order matters (see Pitfall 1).                                                                |
| OTLP collector + Agent 365              | `opentelemetry-sdk`, `opentelemetry-exporter-otlp-*`, A365 core           | Build provider + `BatchSpanProcessor(OTLPSpanExporter(...))` then `configure(...)` | Set `OTEL_EXPORTER_OTLP_ENDPOINT`; collector must be reachable.                          |