Update docs to reflect actual behaviour

docs/reference/configuration.md

@@ -11,24 +11,90 @@ applies_to:
 
 # Configuration [configuration]
 
-Utilize configuration options to adapt the Elastic APM agent to your needs. There are multiple configuration sources, each with different naming conventions for the property key.
+The Elastic APM .NET agent can be configured through environment variables or, for ASP.NET Core applications, through the standard `appsettings.json` file. Both approaches support the same options but use different key names. Environment variable names use the `ELASTIC_APM_` prefix, while `appsettings.json` keys use the `ElasticApm:` prefix.
 
-By default, the agent uses environment variables. Additionally, on ASP.NET Core, the agent plugs into the [Microsoft.Extensions.Configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) infrastructure.
+Environment variables work with every installation method. For ASP.NET Core applications registered with `AddElasticApm()` or `AddAllElasticApm()`, the agent also plugs into the [Microsoft.Extensions.Configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) infrastructure, allowing configuration through `appsettings.json` or any other configured source. For these setups, `appsettings.json` (and other `IConfiguration` sources) take precedence over `ELASTIC_APM_*` environment variables, the agent reads `IConfiguration` first and only falls back to environment variables when no `IConfiguration` value is present. For all other installation methods, including auto-instrumentation via the profiler and standalone .NET applications, environment variables are the only configuration source.
 
 
-## Dynamic configuration [dynamic-configuration]
+## Minimum configuration [minimum-configuration]
 
-Configuration options that are marked with the ![dynamic config](images/dynamic-config.svg "") badge can be changed at runtime when set from a supported source.
+For non-local deployments, configure at least two settings to connect the agent to your APM Server:
+
+| Setting | Environment variable | `appsettings.json` key | Default |
+| --- | --- | --- | --- |
+| Server URL | `ELASTIC_APM_SERVER_URL` | `ElasticApm:ServerUrl` | `http://localhost:8200` |
+| API Key | `ELASTIC_APM_API_KEY` | `ElasticApm:ApiKey` | *(none)* |
+
+::::{note}
+For local development against a default APM Server with no authentication, these defaults are sufficient and no configuration is required.
+::::
+
+It's also recommended to set the service name explicitly:
+
+| Setting | Environment variable | `appsettings.json` key | Default |
+| --- | --- | --- | --- |
+| Service name | `ELASTIC_APM_SERVICE_NAME` | `ElasticApm:ServiceName` | Entry assembly name |
+
+::::{tip}
+`ServiceName` defaults to the name of your entry assembly. Set it explicitly if the auto-detected name is not meaningful, or if multiple services share the same binary.
+::::
+
+**Environment variables** work with every installation method:
 
-The .NET Agent supports [Central configuration](docs-content://solutions/observability/apm/apm-agent-central-configuration.md), which allows you to fine-tune certain configurations via the APM app. This feature is enabled in the Agent by default, with [`CentralConfig` ([1.1])](/reference/config-core.md#config-central-config).
+```sh
+ELASTIC_APM_SERVER_URL=https://your-apm-server:8200
+ELASTIC_APM_API_KEY=your-api-key
+ELASTIC_APM_SERVICE_NAME=my-dotnet-service
+```
 
+For ASP.NET Core applications registered with `AddElasticApm()` or `AddAllElasticApm()`, you can instead set these in `appsettings.json`. See [Configuration on ASP.NET Core](/reference/configuration-on-asp-net-core.md) for details.
 
+```json
+{
+  "ElasticApm": {
+    "ServerUrl": "https://your-apm-server:8200",
+    "ApiKey": "your-api-key",
+    "ServiceName": "my-dotnet-service"
+  }
+}
+```
 
+### Authentication [authentication]
 
+Kibana generates an API key by default when configuring the APM integration, making [`ApiKey`](/reference/config-reporter.md#config-api-key) the recommended authentication method. If your APM Server is configured with a secret token instead, use [`SecretToken`](/reference/config-reporter.md#config-secret-token).
 
+::::{warning}
+Never commit `ApiKey` or `SecretToken` values to source control. Use your platform's secrets management (for example, Azure Key Vault, AWS Secrets Manager, or Kubernetes Secrets) to inject credentials at runtime.
+::::
 
+::::{note}
+If the agent cannot reach the APM Server — for example, due to a missing or incorrect URL or authentication setting — it continues to run but cannot send data. Check the agent logs if you are not seeing data in APM. See [`LogLevel`](/reference/config-supportability.md#config-log-level) to increase log verbosity.
+::::
 
 
+## Configuration reference [configuration-reference]
 
+Configuration options are documented by category. Each option lists its environment variable name, `appsettings.json` key, default value, and type.
 
+| Category | Description |
+| --- | --- |
+| [Core](/reference/config-core.md) | Service identity, sampling, recording, and general behavior |
+| [Reporter](/reference/config-reporter.md) | APM Server connection, authentication, and reporting intervals |
+| [HTTP](/reference/config-http.md) | HTTP request capture, headers, body, and trace context propagation |
+| [Messaging](/reference/config-messaging.md) | Message queue and topic instrumentation |
+| [Stacktrace](/reference/config-stacktrace.md) | Stack trace collection depth and namespace filtering |
+| [Supportability](/reference/config-supportability.md) | Agent log level and diagnostic settings |
+| [All options summary](/reference/config-all-options-summary.md) | Quick-reference table of every option |
+
+For platform-specific configuration setup:
+
+- [Configuration on ASP.NET Core](/reference/configuration-on-asp-net-core.md)
+- [Configuration on ASP.NET](/reference/configuration-on-asp-net.md)
+- [Configuration for Windows Services](/reference/configuration-for-windows-services.md)
+
+
+## Dynamic configuration [dynamic-configuration]
+
+Configuration options that are marked with the ![dynamic config](images/dynamic-config.svg "") badge can be changed at runtime when set from a supported source.
 
+The .NET Agent supports [Central configuration](docs-content://solutions/observability/apm/apm-agent-central-configuration.md), which allows you to fine-tune certain configurations via the APM app. This feature is enabled in the Agent by default, with [`CentralConfig` ([1.1])](/reference/config-core.md#config-central-config). The agent polls for configuration changes at the interval specified by the APM Server, defaulting to 5 minutes. Changes take effect after the next poll.

docs/reference/setup-azure-servicebus.md

@@ -12,31 +12,119 @@ applies_to:
 # Azure Service Bus [setup-azure-servicebus]
 
 
+## Supported versions [_supported_versions_servicebus]
+
+| SDK | Supported versions |
+| --- | --- |
+| `Azure.Messaging.ServiceBus` (current) | ≥7.0.0 <8.0.0 |
+| `Microsoft.Azure.ServiceBus` (legacy, deprecated) | ≥3.0.0 <6.0.0 |
+
+For the full compatibility matrix including supported installation methods, see [Messaging systems](/reference/supported-technologies.md#supported-messaging-systems).
+
+
 ## Quick start [_quick_start_12]
 
-Instrumentation can be enabled for Azure Service Bus by referencing [`Elastic.Apm.Azure.ServiceBus`](https://www.nuget.org/packages/Elastic.Apm.Azure.ServiceBus) package and subscribing to diagnostic events using one of the subscribers:
+This page assumes the core agent is already set up. If not, see [Set up the APM .NET agent](/reference/set-up-apm-net-agent.md) first.
+
+Add the [`Elastic.Apm.Azure.ServiceBus`](https://www.nuget.org/packages/Elastic.Apm.Azure.ServiceBus) NuGet package to your project:
+
+```bash
+dotnet add package Elastic.Apm.Azure.ServiceBus
+```
+
+::::{note}
+If you are using `Azure.Messaging.ServiceBus` (the current SDK), you can alternatively use [profiler auto-instrumentation](/reference/setup-auto-instrumentation.md) or the [OpenTelemetry Bridge](/reference/opentelemetry-bridge.md) without installing this NuGet package. The legacy `Microsoft.Azure.ServiceBus` package does not emit native OpenTelemetry spans and requires this NuGet package.
+
+When this NuGet package is installed alongside a profiler or OpenTelemetry Bridge setup, the dedicated subscriber takes precedence over the bridge to prevent duplicate spans.
+::::
+
+Subscribe the appropriate diagnostics subscriber with the agent. Call this in your application startup, before any Service Bus operations occur:
+
+**If using `Elastic.Apm.NetCoreAll`:**
+The subscribers are registered automatically — no further action is required.
+
+**If using `Azure.Messaging.ServiceBus` (current SDK):**
+
+```csharp
+Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber());
+```
+
+**If using `Microsoft.Azure.ServiceBus` (legacy, deprecated):**
+
+```csharp
+Agent.Subscribe(new MicrosoftAzureServiceBusDiagnosticsSubscriber());
+```
+
+For ASP.NET Core applications, call `Agent.Subscribe()` in your `Program.cs`:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber());
+
+var app = builder.Build();
+app.Run();
+```
 
-1. If the agent is included by referencing the `Elastic.Apm.NetCoreAll` package, the subscribers will be automatically subscribed with the agent, and no further action is required.
-2. If you’re using `Microsoft.Azure.ServiceBus`, subscribe `MicrosoftAzureServiceBusDiagnosticsSubscriber` with the agent
+Once instrumented, Service Bus operations appear as transactions and spans in the APM UI.
 
-    ```csharp
-    Agent.Subscribe(new MicrosoftAzureServiceBusDiagnosticsSubscriber());
-    ```
 
-3. If you’re using `Azure.Messaging.ServiceBus`, subscribe `AzureMessagingServiceBusDiagnosticsSubscriber` with the agent
+## Verify your setup [_verify_setup_servicebus]
 
-    ```csharp
-    Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber());
-    ```
+After configuring the agent and adding the Service Bus instrumentation package:
 
+1. Ensure your application is running and connected to APM Server
+2. Send or receive at least one Service Bus message
+3. Open Kibana and navigate to **Observability → Applications → Service inventory**
+4. Locate your service by name (configured in `ELASTIC_APM_SERVICE_NAME`)
+5. Look for transactions and spans related to Service Bus operations
+
+If you don't see data appearing, check:
+
+* The APM Server URL and service name are correctly configured
+* Network connectivity between your application and APM Server
+* Application logs for any errors or warnings from the Elastic APM agent
+
+
+## Captured operations [_captured_operations]
+
+Transactions represent the top-level operation, typically an inbound receive or message handler invocation. Spans represent child operations within an existing transaction, such as sending messages.
+
+### Transactions [_transactions]
 
 A new transaction is created when
 
-* one or more messages are received from a queue or topic subscription.
-* a message is receive deferred from a queue or topic subscription.
+* a receive operation is initiated against a queue or topic subscription (regardless of whether messages are returned).
+* a receive deferred operation (retrieving a previously deferred message by sequence number) is initiated against a queue or topic subscription.
+* a message is processed via `ServiceBusProcessor` or `ServiceBusSessionProcessor` — the push-based model where the SDK delivers messages to a registered handler. No additional code is required in your handler.
+
+If a receive or receive deferred operation occurs within an existing transaction, a span is created instead.
+
+### Spans [_spans]
 
 A new span is created when there is a current transaction, and when
 
 * one or more messages are sent to a queue or topic.
 * one or more messages are scheduled to a queue or a topic.
 
+### Span links [_span_links]
+
+When receiving or processing a batch of messages, the agent creates a span link for each message back to the producer span that sent it. This preserves the distributed trace across message boundaries and lets you follow each message end-to-end from producer to consumer in the APM UI.
+
+
+## Configure the agent [_configure_agent_servicebus]
+
+Before Service Bus tracing will work, ensure the agent is connected to your APM Server. See [Minimum configuration](/reference/configuration.md#minimum-configuration) to configure:
+
+* `ELASTIC_APM_SERVER_URLS` — APM Server endpoint
+* `ELASTIC_APM_SERVICE_NAME` — Your application's name
+
+::::{tip}
+For development, you can set these via environment variables. For production, use your application's configuration mechanism (for example, `appsettings.json` for ASP.NET Core).
+::::
+
+### Additional messaging options [_additional_messaging_options]
+
+Use [`IgnoreMessageQueues`](/reference/config-messaging.md#config-ignore-message-queues) to exclude specific queues, topics, or subscriptions from being traced. This setting accepts a comma-separated list of wildcard patterns matched against the queue or topic name.
+
+For all other agent configuration options, see [Configuration](/reference/configuration.md).