Skip to content

Latest commit

 

History

History
387 lines (275 loc) · 14.9 KB

packages.asciidoc

File metadata and controls

387 lines (275 loc) · 14.9 KB

NuGet packages

Agent instrumentations are released as a set of NuGet packages available on nuget.org. You can add the Agent and specific instrumentations to your .NET application by referencing one or more of these packages.

Get started

Packages

The following NuGet packages are available:

Elastic.Apm

The core agent package, containing the [public-api] of the agent. It also contains every tracing component to trace classes that are part of .NET Standard 2.0, which includes the monitoring part for HttpClient. Every other Elastic APM package references this package.

Elastic.Apm.NetCoreAll

A meta package that references all other Elastic APM .NET agent package that can automatically configure instrumentation.

If you plan to monitor a typical ASP.NET Core application that depends on the Microsoft.AspNetCore.All package, you should reference this package.

In order to avoid adding unnecessary dependencies in applications that aren’t dependent on the Microsoft.AspNetCore.All package, we also offer some other packages - those are all referenced by the Elastic.Apm.NetCoreAll package.

Elastic.Apm.Extensions.Hosting (added[1.6.0-beta])

A package for agent registration integration with Microsoft.Extensions.Hosting.IHostBuilder registration.

Elastic.Apm.AspNetCore

A package for instrumenting ASP.NET Core applications. The main difference between this package and the Elastic.Apm.NetCoreAll package is that this package only instruments ASP.NET Core by default, whereas Elastic.Apm.NetCoreAll instruments all components that can be automatically configured, such as Entity Framework Core, HTTP calls with HttpClient, database calls to SQL Server with SqlClient, etc. Additional instrumentations can be added when using Elastic.Apm.AspNetCore by referencing the respective NuGet packages and including their configuration code in agent setup.

Elastic.Apm.AspNetFullFramework

A package containing ASP.NET .NET Framework instrumentation.

Elastic.Apm.Azure.CosmosDb

A package containing instrumentation to capture spans for Azure Cosmos DB with Microsoft.Azure.Cosmos, Microsoft.Azure.DocumentDb, and Microsoft.Azure.DocumentDb.Core packages.

Elastic.Apm.Azure.ServiceBus

A package containing instrumentation to capture transactions and spans for messages sent and received from Azure Service Bus with Microsoft.Azure.ServiceBus and Azure.Messaging.ServiceBus packages.

Elastic.Apm.Azure.Storage

A package containing instrumentation to capture spans for interaction with Azure Storage with Azure.Storage.Queues, Azure.Storage.Blobs and Azure.Storage.Files.Shares packages.

Elastic.Apm.EntityFrameworkCore

A package containing Entity Framework Core instrumentation.

Elastic.Apm.EntityFramework6

A package containing an interceptor to automatically create spans for database operations executed by Entity Framework 6 on behalf of the application.

Elastic.Apm.MongoDb

A package containing support for MongoDB.Driver.

Elastic.Apm.SqlClient

A package containing System.Data.SqlClient and Microsoft.Data.SqlClient instrumentation.

Elastic.Apm.StackExchange.Redis

A package containing instrumentation to capture spans for commands sent to redis with StackExchange.Redis package.

Entity Framework Core

Quick start

Instrumentation can be enabled for Entity Framework Core by referencing Elastic.Apm.EntityFrameworkCore package and passing EfCoreDiagnosticsSubscriber to the UseElasticApm method in case of ASP.NET Core as following

app.UseElasticApm(Configuration, new EfCoreDiagnosticsSubscriber()); (1)

  1. Configuration is the IConfiguration instance passed to your Startup type

or passing EfCoreDiagnosticsSubscriber to the Subscribe method

Agent.Subscribe(new EfCoreDiagnosticsSubscriber());

Instrumentation listens for diagnostic events raised by Microsoft.EntityFrameworkCore 2.x+, creating database spans for executed commands.

Entity Framework 6

Quick start

You can enable auto instrumentation for Entity Framework 6 by referencing the Elastic.Apm.EntityFramework6 package and including the Ef6Interceptor interceptor in your application’s web.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <entityFramework>
        <interceptors>
            <interceptor type="Elastic.Apm.EntityFramework6.Ef6Interceptor, Elastic.Apm.EntityFramework6" />
        </interceptors>
    </entityFramework>
</configuration>

As an alternative to registering the interceptor via the configuration, you can register it in the application code:

DbInterception.Add(new Elastic.Apm.EntityFramework6.Ef6Interceptor());

For example, in an ASP.NET application, you can place the above call in the Application_Start method.

Instrumentation works with EntityFramework 6.2+ NuGet packages.

Note
 Be careful not to execute DbInterception.Add for the same interceptor type more than once, as this will register multiple instances, causing multiple database spans to be captured for every SQL command.

Elasticsearch

Quick start

Instrumentation can be enabled for Elasticsearch when using the official Elasticsearch clients, Elasticsearch.Net and Nest, by referencing Elastic.Apm.Elasticsearch package and passing ElasticsearchDiagnosticsSubscriber to the UseElasticApm method in case of ASP.NET Core as following

app.UseElasticApm(Configuration, new ElasticsearchDiagnosticsSubscriber()); (1)

  1. Configuration is the IConfiguration instance passed to your Startup type

or passing ElasticsearchDiagnosticsSubscriber to the Subscribe method

Agent.Subscribe(new ElasticsearchDiagnosticsSubscriber());

Instrumentation listens for activities raised by Elasticsearch.Net and Nest 7.6.0+, creating spans for executed requests.

Important

If you’re using Elasticsearch.Net and Nest 7.10.1 or 7.11.0, upgrade to at least 7.11.1 which fixes a bug in span capturing.

gRPC

Quick start

Automatic instrumentation for gRPC can be enabled for both client-side and server-side gRPC calls.

Automatic instrumentation for ASP.NET Core server-side is built in to NuGet package

Automatic instrumentation can be enabled for the client-side by referencing Elastic.Apm.GrpcClient package and passing GrpcClientDiagnosticListener to the UseElasticApm method in case of ASP.NET Core

app.UseElasticApm(Configuration, new GrpcClientDiagnosticListener()); (1)

  1. Configuration is the IConfiguration instance passed to your Startup type

or passing GrpcClientDiagnosticListener to the Subscribe method

Agent.Subscribe(new GrpcClientDiagnosticListener());

Diagnostic events from Grpc.Net.Client are captured as spans.

SqlClient

Quick start

You can enable auto instrumentation for System.Data.SqlClient or Microsoft.Data.SqlClient by referencing Elastic.Apm.SqlClient package and passing SqlClientDiagnosticSubscriber to the UseElasticApm method in case of ASP.NET Core as it shown in example:

// Enable tracing of outgoing db requests
app.UseElasticApm(Configuration, new SqlClientDiagnosticSubscriber()); (1)

  1. Configuration is the IConfiguration instance passed to your Startup type

or passing SqlClientDiagnosticSubscriber to the Subscribe method and make sure that the code is called only once, otherwise the same database call could be captured multiple times:

// Enable tracing of outgoing db requests
Agent.Subscribe(new SqlClientDiagnosticSubscriber());
Note

Auto instrumentation for System.Data.SqlClient is available for both .NET Core and .NET Framework applications, however, support of .NET Framework has one limitation: command text cannot be captured.

Auto instrumentation for Microsoft.Data.SqlClient is available only for .NET Core at the moment.

As an alternative to using the Elastic.Apm.SqlClient package to instrument database calls, see [setup-auto-instrumentation].

StackExchange.Redis

Quick start

Instrumentation can be enabled for StackExchange.Redis by referencing Elastic.Apm.StackExchange.Redis package and calling the UseElasticApm() extension method defined in Elastic.Apm.StackExchange.Redis, on IConnectionMultiplexer

// using Elastic.Apm.StackExchange.Redis;

var connection = await ConnectionMultiplexer.ConnectAsync("<redis connection>");
connection.UseElasticApm();

A callback is registered with the IConnectionMultiplexer to provide a profiling session for each transaction and span that captures redis commands sent with IConnectionMultiplexer.

Azure Cosmos DB

Quick start

Instrumentation can be enabled for Azure Cosmos DB by referencing Elastic.Apm.Azure.CosmosDb package and subscribing to diagnostic events.

Agent.Subscribe(new AzureCosmosDbDiagnosticsSubscriber());

Diagnostic events from Microsoft.Azure.Cosmos, Microsoft.Azure.DocumentDb, and Microsoft.Azure.DocumentDb.Core are captured as DB spans.

Azure Service Bus

Quick start

Instrumentation can be enabled for Azure Service Bus by referencing Elastic.Apm.Azure.ServiceBus package and subscribing to diagnostic events using one of the subscribers:

  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

    Agent.Subscribe(new MicrosoftAzureServiceBusDiagnosticsSubscriber());

  3. If you’re using Azure.Messaging.ServiceBus, subscribe AzureMessagingServiceBusDiagnosticsSubscriber with the agent

    Agent.Subscribe(new AzureMessagingServiceBusDiagnosticsSubscriber());

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 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.

Azure Storage

Quick start

Instrumentation can be enabled for Azure Storage by referencing Elastic.Apm.Azure.Storage package and subscribing to diagnostic events using one of the subscribers:

  • 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.

  • If you’re using Azure.Storage.Blobs, subscribe AzureBlobStorageDiagnosticsSubscriber with the agent

    Agent.Subscribe(new AzureBlobStorageDiagnosticsSubscriber());

  • If you’re using Azure.Storage.Queues, subscribe AzureQueueStorageDiagnosticsSubscriber with the agent

    Agent.Subscribe(new AzureQueueStorageDiagnosticsSubscriber());

  • If you’re using Azure.Storage.Files.Shares, subscribe AzureFileShareStorageDiagnosticsSubscriber with the agent

    Agent.Subscribe(new AzureFileShareStorageDiagnosticsSubscriber());

For Azure Queue storage,

  • A new transaction is created when one or more messages are received from a queue

  • A new span is created when there is a current transaction, and when a message is sent to a queue

For Azure Blob storage, a new span is created when there is a current transaction and when a request is made to blob storage.

For Azure File Share storage, a new span is crated when there is a current transaction and when a request is made to file storage.

MongoDB

Quick start

Instrumentation for MongoDB works with the official MongoDb.Driver 2.4.4+ driver packages. A prerequisite for auto instrumentation is to configure the MongoClient with MongoDbEventSubscriber:

var settings = MongoClientSettings.FromConnectionString(mongoConnectionString);

settings.ClusterConfigurator = builder => builder.Subscribe(new MongoDbEventSubscriber());
var mongoClient = new MongoClient(settings);

Once the above configuration is in place

  • if the agent is included by referencing the Elastic.Apm.NetCoreAll package, it will automatically capture calls to MongoDB on every active transaction, and no further action is required.

  • you can manually activate auto instrumentation from the Elastic.Apm.MongoDb package by calling

Agent.Subscribe(new MongoDbDiagnosticsSubscriber());
Important

MongoDB integration is currently supported on .NET Core and newer. Due to MongoDb.Driver assemblies not being strongly named, they cannot be used with Elastic APM’s strongly named assemblies on .NET Framework.