Seguimiento de las operaciones personalizadas con el SDK de .NET para Application InsightsTrack custom operations with Application Insights .NET SDK

Los SDK de Azure Application Insights realizan el seguimiento automático de las solicitudes HTTP de entrada y las llamadas a los servicios dependientes, como solicitudes HTTP y consultas SQL.Azure Application Insights SDKs automatically track incoming HTTP requests and calls to dependent services, such as HTTP requests and SQL queries. El seguimiento y la correlación de las solicitudes y dependencias le ofrece visibilidad en la capacidad de respuesta de toda la aplicación y la confiabilidad en todos los microservicios que combinan esta aplicación.Tracking and correlation of requests and dependencies give you visibility into the whole application's responsiveness and reliability across all microservices that combine this application.

Hay una clase de patrones de aplicación que no se admiten de forma genérica.There is a class of application patterns that can't be supported generically. La supervisión correcta de estos patrones requiere la instrumentación manual de código.Proper monitoring of such patterns requires manual code instrumentation. En este artículo se abordan algunos patrones que pueden requerir la instrumentación manual, como el procesamiento de colas personalizadas y la ejecución de tareas de larga duración en segundo plano.This article covers a few patterns that might require manual instrumentation, such as custom queue processing and running long-running background tasks.

En este documento se proporcionan instrucciones sobre cómo realizar el seguimiento de operaciones personalizadas con el SDK de Application Insights.This document provides guidance on how to track custom operations with the Application Insights SDK. Esta documentación es relevante para:This documentation is relevant for:

  • Application Insights para .NET (también conocido como Base SDK) versión 2.4+.Application Insights for .NET (also known as Base SDK) version 2.4+.
  • Application Insights para aplicaciones web (con ASP.NET) versión 2.4+.Application Insights for web applications (running ASP.NET) version 2.4+.
  • Application Insights para ASP.NET Core versión 2.1+.Application Insights for ASP.NET Core version 2.1+.

Información generalOverview

Una operación es una parte de trabajo lógica ejecutada por una aplicación.An operation is a logical piece of work run by an application. Tiene un nombre, una hora de inicio, una duración, un resultado y un contexto de ejecución como el nombre de usuario, las propiedades y el resultado.It has a name, start time, duration, result, and a context of execution like user name, properties, and result. Si la operación B inició la operación A, la operación B se establece como un elemento primario de A. Una operación solo puede tener un elemento primario, pero puede tener muchas operaciones secundarias.If operation A was initiated by operation B, then operation B is set as a parent for A. An operation can have only one parent, but it can have many child operations. Para más información sobre las operaciones y la correlación de telemetría, vea Correlación de telemetría en Azure Application Insights.For more information on operations and telemetry correlation, see Azure Application Insights telemetry correlation.

En el SDK de .NET para Application Insights se describe la operación mediante la clase abstracta OperationTelemetry y sus descendientes RequestTelemetry y DependencyTelemetry.In the Application Insights .NET SDK, the operation is described by the abstract class OperationTelemetry and its descendants RequestTelemetry and DependencyTelemetry.

Seguimiento de operaciones de entradaIncoming operations tracking

El SDK web de Application Insights recopila automáticamente las solicitudes HTTP para las aplicaciones ASP.NET que se ejecutan en una canalización IIS y todas las aplicaciones ASP.NET Core.The Application Insights web SDK automatically collects HTTP requests for ASP.NET applications that run in an IIS pipeline and all ASP.NET Core applications. Hay soluciones admitidas por la comunidad para otras plataformas y marcos de trabajo.There are community-supported solutions for other platforms and frameworks. Pero si la aplicación no es compatible con ninguna solución admitida por los estándares o la comunidad, puede instrumentarla de forma manual.However, if the application isn't supported by any of the standard or community-supported solutions, you can instrument it manually.

Otro ejemplo que requiere seguimiento personalizado es el proceso de trabajo que recibe los elementos de la cola.Another example that requires custom tracking is the worker that receives items from the queue. Para algunas colas, se realiza un seguimiento como dependencia de la llamada para agregar un mensaje a esta cola.For some queues, the call to add a message to this queue is tracked as a dependency. Pero la operación general que describe el procesamiento de mensajes no se recopila automáticamente.However, the high-level operation that describes message processing is not automatically collected.

Ahora vamos a ver cómo se puede realizar un seguimiento de tales operaciones.Let's see how such operations could be tracked.

Generalmente, la tarea consiste en crear RequestTelemetry y establecer propiedades conocidas.On a high level, the task is to create RequestTelemetry and set known properties. Una vez finalizada la operación, se realiza el seguimiento de la telemetría.After the operation is finished, you track the telemetry. En el siguiente ejemplo se muestra esta tarea.The following example demonstrates this task.

Solicitud HTTP en una aplicación autohospedada de OwinHTTP request in Owin self-hosted app

En este ejemplo, el contexto de seguimiento se propaga según el protocolo HTTP para la correlación.In this example, trace context is propagated according to the HTTP Protocol for Correlation. Debe esperar recibir los encabezados que se describen ahí.You should expect to receive headers that are described there.

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // you may create a new TelemetryConfiguration instance, reuse one you already have
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

El Protocolo HTTP para la correlación también declara el encabezado Correlation-Context.The HTTP Protocol for Correlation also declares the Correlation-Context header. Pero aquí se omite para simplificar.However, it's omitted here for simplicity.

Instrumentación de colasQueue instrumentation

Aunque existen el contexto de seguimiento de W3C y el protocolo HTTP para la correlación para pasar los detalles de la correlación con la solicitud HTTP, todos los protocolos de cola tienen que definir cómo se transmiten los mismos detalles junto con el mensaje de cola.While there are W3C Trace Context and HTTP Protocol for Correlation to pass correlation details with HTTP request, every queue protocol has to define how the same details are passed along the queue message. Algunos protocolos de cola (por ejemplo, AMQP) permiten pasar metadatos adicionales, y otros (como una cola de Azure Storage) requieren que el contexto se codifique en la carga del mensaje.Some queue protocols (such as AMQP) allow passing additional metadata and some others (such Azure Storage Queue) require the context to be encoded into the message payload.

Nota

  • Todavía no se admite el seguimiento entre componentes para las colas con HTTP, si el productor y el consumidor envían telemetría a distintos recursos de Application Insights, la experiencia de diagnósticos de transacción y el mapa de aplicación muestran transacciones y asignaciones de un extremo a otro.Cross-component tracing is not supported for queues yet With HTTP, if your producer and consumer send telemetry to different Application Insights resources, Transaction Diagnostics Experience and Application Map show transactions and map end-to-end. En el caso de las colas, todavía no se admite.In case of queues this is not supported yet.

Cola de Service BusService Bus Queue

Application Insights realiza un seguimiento de las llamadas de mensajería de Service Bus con la nueva versión 3.0.0 del cliente Microsoft Azure ServiceBus para .NET y con versiones posteriores.Application Insights tracks Service Bus Messaging calls with the new Microsoft Azure ServiceBus Client for .NET version 3.0.0 and higher. Si usa un patrón de controlador de mensajes para procesar mensajes, ya ha terminado: se realizará el seguimiento automático de todas las llamadas de Service Bus que se hayan hecho mediante el servicio y se correlacionarán con otros elementos de telemetría.If you use message handler pattern to process messages, you are done: all Service Bus calls done by your service are automatically tracked and correlated with other telemetry items. Consulte el artículo sobre el seguimiento del cliente Service Bus con Microsoft Application Insights si desea procesar los mensajes manualmente.Refer to the Service Bus client tracing with Microsoft Application Insights if you manually process messages.

Si usa el paquete WindowsAzure.ServiceBus, siga leyendo; en los ejemplos siguientes se muestra cómo realizar un seguimiento de las llamadas y correlacionarlas en Service Bus, ya que la cola de Service Bus usa el protocolo AMQP y Application Insights no realiza un seguimiento automático de las operaciones de cola.If you use WindowsAzure.ServiceBus package, read further - following examples demonstrate how to track (and correlate) calls to the Service Bus as Service Bus queue uses AMQP protocol and Application Insights doesn't automatically track queue operations. Los identificadores de correlación se transmiten en las propiedades del mensaje.Correlation identifiers are passed in the message properties.

Poner en colaEnqueue

public async Task Enqueue(string payload)
{
    // StartOperation is a helper method that initializes the telemetry item
    // and allows correlation of this operation with its parent and children.
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queueName);
    
    operation.Telemetry.Type = "Azure Service Bus";
    operation.Telemetry.Data = "Enqueue " + queueName;

    var message = new BrokeredMessage(payload);
    // Service Bus queue allows the property bag to pass along with the message.
    // We will use them to pass our correlation identifiers (and other context)
    // to the consumer.
    message.Properties.Add("ParentId", operation.Telemetry.Id);
    message.Properties.Add("RootId", operation.Telemetry.Context.Operation.Id);

    try
    {
        await queue.SendAsync(message);
        
        // Set operation.Telemetry Success and ResponseCode here.
        operation.Telemetry.Success = true;
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Set operation.Telemetry Success and ResponseCode here.
        operation.Telemetry.Success = false;
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

ProcesoProcess

public async Task Process(BrokeredMessage message)
{
    // After the message is taken from the queue, create RequestTelemetry to track its processing.
    // It might also make sense to get the name from the message.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };

    var rootId = message.Properties["RootId"].ToString();
    var parentId = message.Properties["ParentId"].ToString();
    // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
    requestTelemetry.Context.Operation.Id = rootId;
    requestTelemetry.Context.Operation.ParentId = parentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Cola de Azure StorageAzure Storage queue

En el ejemplo siguiente se muestra cómo realizar el seguimiento de operaciones de cola de Azure Storage y poner en correlación la telemetría entre el productor, el consumidor y Azure Storage.The following example shows how to track the Azure Storage queue operations and correlate telemetry between the producer, the consumer, and Azure Storage.

La cola de Storage tiene una API HTTP.The Storage queue has an HTTP API. El recolector de dependencias de Application Insights realiza el seguimiento de todas las llamadas a la cola para las solicitudes HTTP.All calls to the queue are tracked by the Application Insights Dependency Collector for HTTP requests. Se configura de forma predeterminada en las aplicaciones ASP.NET y ASP.NET Core, con otros tipos de aplicación, puede consultar la documentación de las aplicaciones de consola.It is configured by default on ASP.NET and ASP.NET Core applications, with other kinds of applicaiton, you can refer to console applications documentation

Es posible que también quiera poner en correlación el identificador de operación de Application Insights con el identificador de solicitud de Storage.You also might want to correlate the Application Insights operation ID with the Storage request ID. Para obtener información sobre cómo establecer y obtener un cliente de solicitud de Storage y un identificador de solicitud de servidor, vea Supervisión, diagnóstico y solución de problemas de Azure Storage.For information on how to set and get a Storage request client and a server request ID, see Monitor, diagnose, and troubleshoot Azure Storage.

Poner en colaEnqueue

Como las colas de Storage admiten la API de HTTP, Application Insights realiza el seguimiento automático de todas las operaciones en la cola.Because Storage queues support the HTTP API, all operations with the queue are automatically tracked by Application Insights. En muchos casos, esta instrumentación debería ser suficiente.In many cases, this instrumentation should be enough. Pero para poner en correlación seguimientos en el lado del consumidor con seguimientos del productor, tiene que pasar un contexto de correlación de forma similar a como se hace en el Protocolo HTTP para la correlación.However, to correlate traces on the consumer side with producer traces, you must pass some correlation context similarly to how we do it in the HTTP Protocol for Correlation.

En este ejemplo se muestra cómo realizar un seguimiento de la operación Enqueue.This example shows how to track the Enqueue operation. Puede:You can:

  • Poner en correlación los reintentos (si existen) : todos tienen un elemento primario común que es la operación Enqueue.Correlate retries (if any): They all have one common parent that's the Enqueue operation. En caso contrario, se realiza su seguimiento como elementos secundarios de la solicitud de entrada.Otherwise, they're tracked as children of the incoming request. Si hay varias solicitudes lógicas a la cola, podría ser difícil buscar qué llamada generó los reintentos.If there are multiple logical requests to the queue, it might be difficult to find which call resulted in retries.
  • Poner en correlación los registros de almacenamiento (si es necesario y cuando sea necesario) : se correlacionan con la telemetría de Application Insights.Correlate Storage logs (if and when needed): They're correlated with Application Insights telemetry.

La operación Enqueue es el elemento secundario de una operación principal (por ejemplo, una solicitud HTTP de entrada).The Enqueue operation is the child of a parent operation (for example, an incoming HTTP request). La llamada de dependencia HTTP es el elemento secundario de la operación Enqueue y el descendiente de la solicitud de entrada:The HTTP dependency call is the child of the Enqueue operation and the grandchild of the incoming request:

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

Para reducir la cantidad de telemetría que notifica la aplicación o si no quiere realizar el seguimiento de la operación Enqueue por otras razones, use directamente la API Activity:To reduce the amount of telemetry your application reports or if you don't want to track the Enqueue operation for other reasons, use the Activity API directly:

  • Cree (e inicie) una nueva Activity en lugar de iniciar la operación de Application Insights.Create (and start) a new Activity instead of starting the Application Insights operation. No es necesario asignar ninguna propiedad en este elemento, excepto el nombre de la operación.You do not need to assign any properties on it except the operation name.
  • Serialice yourActivity.Id en la carga del mensaje en lugar de operation.Telemetry.Id.Serialize yourActivity.Id into the message payload instead of operation.Telemetry.Id. También se puede usar Activity.Current.Id.You can also use Activity.Current.Id.

Quitar de la colaDequeue

Al igual que Enqueue, Application Insights realiza el seguimiento automático de la solicitud HTTP a la cola de Storage.Similarly to Enqueue, an actual HTTP request to the Storage queue is automatically tracked by Application Insights. Pero supuestamente la operación Enqueue se produce en el contexto principal, por ejemplo en un contexto de solicitud de entrada.However, the Enqueue operation presumably happens in the parent context, such as an incoming request context. Los SDK de Application Insights correlacionan automáticamente esta operación (y su elemento HTTP) con la solicitud primaria y otra telemetría notificada en el mismo ámbito.Application Insights SDKs automatically correlate such an operation (and its HTTP part) with the parent request and other telemetry reported in the same scope.

La operación Dequeue es complicada.The Dequeue operation is tricky. El SDK de Application Insights realiza automáticamente el seguimiento de las solicitudes HTTP.The Application Insights SDK automatically tracks HTTP requests. Pero desconoce el contexto de correlación hasta que se analiza el mensaje.However, it doesn't know the correlation context until the message is parsed. No es posible poner en correlación la solicitud HTTP para obtener el mensaje con el resto de la telemetría, en especial cuando se recibe más de un mensaje.It's not possible to correlate the HTTP request to get the message with the rest of the telemetry especially when more than one message is received.

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;
    
    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

ProcesoProcess

En el ejemplo siguiente, se realiza el seguimiento de un mensaje de entrada de forma similar a cómo se realiza en una solicitud HTTP de entrada:In the following example, an incoming message is tracked in a manner similarly to incoming HTTP request:

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Del mismo modo, se pueden instrumentar otras operaciones de cola.Similarly, other queue operations can be instrumented. Una operación de lectura se debe instrumentalizar de una manera similar a la de una operación de quitar de la cola.A peek operation should be instrumented in a similar way as a dequeue operation. La instrumentación de las operaciones de administración de cola no es necesaria.Instrumenting queue management operations isn't necessary. Application Insights realiza el seguimiento de las operaciones como HTTP y en la mayoría de los casos es suficiente.Application Insights tracks operations such as HTTP, and in most cases, it's enough.

Al instrumentar la eliminación de mensajes, asegúrese de establecer los identificadores de la operación (correlación).When you instrument message deletion, make sure you set the operation (correlation) identifiers. Como alternativa, puede usar la API de Activity.Alternatively, you can use the Activity API. No es necesario establecer identificadores de operaciones en los elementos de telemetría, porque el SDK de Application Insights lo hace automáticamente:Then you don't need to set operation identifiers on the telemetry items because Application Insights SDK does it for you:

  • Cree una nueva Activity después de que tenga un elemento de la cola.Create a new Activity after you've got an item from the queue.
  • Use Activity.SetParentId(message.ParentId) para poner en correlación los registros de consumidor y productor.Use Activity.SetParentId(message.ParentId) to correlate consumer and producer logs.
  • Inicie la Activity.Start the Activity.
  • Realice el seguimiento de las operaciones de quitar de la cola, proceso y eliminación mediante los asistentes Start/StopOperation.Track dequeue, process, and delete operations by using Start/StopOperation helpers. Hágalo desde el mismo flujo de control asincrónico (contexto de ejecución).Do it from the same asynchronous control flow (execution context). De esta forma, se correlacionan correctamente.In this way, they're correlated properly.
  • Pare la Activity.Stop the Activity.
  • Use Start/StopOperation o llame a la telemetría de Track manualmente.Use Start/StopOperation, or call Track telemetry manually.

Tipos de dependenciaDependency Types

Application Insights usa el tipo de dependencia para personalizar las experiencias de la interfaz de usuario.Application Insights uses dependency type to customize UI experiences. En el caso de las colas, reconoce los siguientes tipos de DependencyTelemetry que mejoran la experiencia de diagnósticos de transacción:For queues it recognizes following types of DependencyTelemetry that improve Transaction diagnostics experience:

  • Azure queue para colas de Azure StorageAzure queue for Azure Storage Queues
  • Azure Event Hubs para Azure Event HubsAzure Event Hubs for Azure Event Hubs
  • Azure Service Bus para Azure Service BusAzure Service Bus for Azure Service Bus

Procesamiento por lotesBatch processing

En algunas colas, se pueden quitar de la cola varios mensajes con una solicitud.With some queues, you can dequeue multiple messages with one request. El procesamiento de este tipo de mensajes es supuestamente independiente y pertenece a las distintas operaciones lógicas.Processing such messages is presumably independent and belongs to the different logical operations. No es posible poner en correlación la operación Dequeue con el mensaje determinado que va a procesarse.It's not possible to correlate the Dequeue operation to a particular message being processed.

Cada mensaje debe procesarse en su propio flujo de control asincrónico.Each message should be processed in its own asynchronous control flow. Para más información, vea la sección Seguimiento de dependencias de salida.For more information, see the Outgoing dependencies tracking section.

Tareas en segundo plano de ejecución prolongadaLong-running background tasks

Algunas aplicaciones inician operaciones de larga ejecución que es posible que se deban a solicitudes del usuario.Some applications start long-running operations that might be caused by user requests. Desde la perspectiva del seguimiento o la instrumentación, no es diferente de la instrumentación de solicitudes o dependencias:From the tracing/instrumentation perspective, it's not different from request or dependency instrumentation:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

En este ejemplo, telemetryClient.StartOperation crea DependencyTelemetry y rellena el contexto de correlación.In this example, telemetryClient.StartOperation creates DependencyTelemetry and fills the correlation context. Supongamos que tiene una operación principal creada por las solicitudes de entrada que programaron la operación.Let's say you have a parent operation that was created by incoming requests that scheduled the operation. Siempre que BackgroundTask se inicie en el mismo flujo de control asincrónico que una solicitud de entrada, se correlaciona con esa operación principal.As long as BackgroundTask starts in the same asynchronous control flow as an incoming request, it's correlated with that parent operation. BackgroundTask y todos los elementos de telemetría anidados se correlacionan automáticamente con la solicitud que la causó incluso después de que finalice la solicitud.BackgroundTask and all nested telemetry items are automatically correlated with the request that caused it, even after the request ends.

Cuando la tarea se inicia desde el subproceso en segundo plano que no tiene ninguna operación (Activity) asociada a él, BackgroundTask no tiene ningún elemento primario.When the task starts from the background thread that doesn't have any operation (Activity) associated with it, BackgroundTask doesn't have any parent. Pero puede tener operaciones anidadas.However, it can have nested operations. Todos los elementos de telemetría notificados desde la tarea se ponen en correlación con la DependencyTelemetry creada en BackgroundTask.All telemetry items reported from the task are correlated to the DependencyTelemetry created in BackgroundTask.

Seguimiento de dependencias de salidaOutgoing dependencies tracking

Puede realizar el seguimiento de su propio tipo de dependencia o de una operación que no es compatible con Application Insights.You can track your own dependency kind or an operation that's not supported by Application Insights.

El método Enqueue de la cola de Service Bus o la cola de Storage puede servir como ejemplo de este seguimiento personalizado.The Enqueue method in the Service Bus queue or the Storage queue can serve as examples for such custom tracking.

El enfoque general para el seguimiento de dependencias personalizadas es este:The general approach for custom dependency tracking is to:

  • Llame al método TelemetryClient.StartOperation (extensión) que rellena las propiedades de DependencyTelemetry que se necesitan para la correlación y algunas otras (inicio de la marca de tiempo, duración).Call the TelemetryClient.StartOperation (extension) method that fills the DependencyTelemetry properties that are needed for correlation and some other properties (start time stamp, duration).
  • Establezca otras propiedades personalizadas en DependencyTelemetry, como el nombre y cualquier otro contexto que se necesite.Set other custom properties on the DependencyTelemetry, such as the name and any other context you need.
  • Realice una llamada de dependencia y espere.Make a dependency call and wait for it.
  • Detenga la operación con StopOperation cuando finalice.Stop the operation with StopOperation when it's finished.
  • Controle las excepciones.Handle exceptions.
public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

Desechar la operación provoca que la operación se detenga, por lo que puede hacerlo en lugar de llamar a StopOperation.Disposing operation causes operation to be stopped, so you may do it instead of calling StopOperation.

Advertencia: en algunos casos, una excepción no controlada puede impedir la llamada a finally, por lo que puede que no se realice un seguimiento de las operaciones.Warning: in some cases unhanded exception may prevent finally to be called so operations may not be tracked.

Seguimiento y procesamiento de operaciones paralelasParallel operations processing and tracking

StopOperation solo detiene la operación que se inició.StopOperation only stops the operation that was started. Si la operación de ejecución actual no coincide con la que quiere detener, StopOperation no hace nada.If the current running operation doesn't match the one you want to stop, StopOperation does nothing. Es posible que suceda esta situación si se inician varias operaciones en paralelo en el mismo contexto de ejecución:This situation might happen if you start multiple operations in parallel in the same execution context:

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Asegúrese de llamar siempre a StartOperation y de procesar la operación en el mismo método async para aislar las operaciones que se ejecutan en paralelo.Make sure you always call StartOperation and process operation in the same async method to isolate operations running in parallel. Si la operación es sincrónica o no asincrónica, encapsule el proceso y realice un seguimiento con Task.Run:If operation is synchronous (or not async), wrap process and track with Task.Run:

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Operaciones de ApplicationInsights frente a System.Diagnostics.ActivityApplicationInsights operations vs System.Diagnostics.Activity

System.Diagnostics.Activity representa el contexto de seguimiento distribuido y lo utilizan las plataformas y las bibliotecas para crear y propagar el contexto dentro y fuera del proceso, así como correlacionar los elementos de telemetría.System.Diagnostics.Activity represents the distributed tracing context and is used by frameworks and libraries to create and propagate context inside and outside of the process and correlate telemetry items. La actividad funciona junto System.Diagnostics.DiagnosticSource, que es el mecanismo de notificación entre la plataforma o la biblioteca para notificar de eventos interesantes (solicitudes entrantes o salientes, excepciones, etc.).Activity works together with System.Diagnostics.DiagnosticSource - the notification mechanism between the framework/library to notify about interesting events (incoming or outgoing requests, exceptions, etc).

Las actividades son los ciudadanos de primera clase en Application Insights y la recopilación automática de dependencias y solicitudes se basa en gran medida en ellas junto con los eventos DiagnosticSource.Activities are first-class citizens in Application Insights and automatic dependency and request collection relies heavily on them along with DiagnosticSource events. Si crea una actividad en la aplicación, no se producirá la creación de telemetría de Application Insights.If you create Activity in your application - it would not result in Application Insights telemetry being created. Application Insights debe recibir los eventos de DiagnosticSource y conocer los nombres y las cargas de los eventos para convertir la actividad en telemetría.Application Insights needs to receive DiagnosticSource events and know the events names and payloads to translate Activity into telemetry.

Cada operación de Application Insights (solicitud o dependencia) implica Activity; cuando se llama a StartOperation, se crea la actividad subyacente.Each Application Insights operation (request or dependency) involves Activity - when StartOperation is called, it creates Activity underneath. StartOperation es el método recomendado para realizar el seguimiento de las telemetrías de solicitudes o de dependencias manualmente y asegurarse de que todo está correlacionado.StartOperation is the recommended way to track request or dependency telemetries manually and ensure everything is correlated.

Pasos siguientesNext steps