Skip to content

Commit 01c255b

Browse files
ktoliverktoliver
authored
Merge pull request #77631 from cijothomas/cithomas/dependencies
Application Insights Dependency doc rewrite.
2 parents 74b3732 + 0a6450b commit 01c255b

File tree

1 file changed

+151
-66
lines changed

1 file changed

+151
-66
lines changed

‎articles/azure-monitor/app/asp-net-dependencies.md

Lines changed: 151 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Dependency Tracking in Azure Application Insights | Microsoft Docs
3-
description: Analyze usage, availability, and performance of your on-premises or Microsoft Azure web application with Application Insights.
3+
description: Monitor dependency calls from your on-premises or Microsoft Azure web application with Application Insights.
44
services: application-insights
55
documentationcenter: .net
66
author: mrbullwinkle
@@ -15,73 +15,185 @@ ms.date: 12/06/2018
1515
ms.author: mbullwin
1616

1717
---
18-
# Set up Application Insights: Dependency tracking
19-
A *dependency* is an external component that is called by your app. It's typically a service called using HTTP, or a database, or a file system. [Application Insights](../../azure-monitor/app/app-insights-overview.md) measures how long your application waits for dependencies and how often a dependency call fails. You can investigate specific calls, and relate them to requests and exceptions.
18+
# Dependency Tracking in Azure Application Insights
2019

21-
The out-of-the-box dependency monitor currently reports calls to these types of dependencies:
20+
A *dependency* is an external component that is called by your app. It's typically a service called using HTTP, or a database, or a file system. [Application Insights](../../azure-monitor/app/app-insights-overview.md) measures the duration of dependency calls, whether its failing or not, along with additional information like name of dependency and so on. You can investigate specific dependency calls, and correlate them to requests and exceptions.
2221

23-
* Server
24-
* SQL databases
25-
* ASP.NET web and WCF services that use HTTP-based bindings
26-
* Local or remote HTTP calls
27-
* Azure Cosmos DB, table, blob storage, and queue
28-
* Web pages
29-
* AJAX calls
22+
## Automatically tracked dependencies
3023

31-
Monitoring works by using [byte code instrumentation](https://msdn.microsoft.com/library/z9z62c29.aspx) around select methods or based on DiagnosticSource callbacks (in the latest .NET SDKs) from the .NET Framework. Performance overhead is minimal.
24+
Application Insights SDKs for .NET and .NET Core ships with `DependencyTrackingTelemetryModule` which is a Telemetry Module that automatically collects dependencies. This dependency collection is enabled automatically for [ASP.NET](https://docs.microsoft.com/azure/azure-monitor/app/asp-net) and [ASP.NET Core](https://docs.microsoft.com/azure/azure-monitor/app/asp-net-core) applications, when configured as per the linked official docs. `DependencyTrackingTelemetryModule` is shipped as [this](https://www.nuget.org/packages/Microsoft.ApplicationInsights.DependencyCollector/) NuGet package, and is brought automatically when using either of the NuGet packages `Microsoft.ApplicationInsights.Web` or `Microsoft.ApplicationInsights.AspNetCore`.
3225

33-
You can also write your own SDK calls to monitor other dependencies, both in the client and server code, using the [TrackDependency API](../../azure-monitor/app/api-custom-events-metrics.md#trackdependency).
26+
`DependencyTrackingTelemetryModule` currently tracks the following dependencies automatically:
3427

35-
> [!NOTE]
36-
> Azure Cosmos DB is tracked automatically only if [HTTP/HTTPS](../../cosmos-db/performance-tips.md#networking) is used. TCP mode won't be captured by Application Insights.
28+
|Dependencies |Details|
29+
|---------------|-------|
30+
|Http/Https | Local or Remote http/https calls |
31+
|WCF calls| Only tracked automatically if Http-based bindings are used.|
32+
|SQL | Calls made with `SqlClient`. See [this](##advanced-sql-tracking-to-get-full-sql-query) for capturing SQL query . |
33+
|[Azure storage (Blob, Table, Queue )](https://www.nuget.org/packages/WindowsAzure.Storage/) | Calls made with Azure Storage Client. |
34+
|[EventHub Client SDK](https://www.nuget.org/packages/Microsoft.Azure.EventHubs) | Version 1.1.0 and above. |
35+
|[ServiceBus Client SDK](https://www.nuget.org/packages/Microsoft.Azure.ServiceBus)| Version 3.0.0 and above. |
36+
|Azure Cosmos DB | Only tracked automatically if HTTP/HTTPS is used. TCP mode won't be captured by Application Insights. |
3737

38-
## Set up dependency monitoring
39-
Partial dependency information is collected automatically by the [Application Insights SDK](asp-net.md). To get complete data, install the appropriate agent for the host server.
4038

41-
| Platform | Install |
39+
## Setup automatic dependency tracking in Console Apps
40+
41+
To automatically track dependencies from .NET/.NET Core console apps, install the Nuget package `Microsoft.ApplicationInsights.DependencyCollector`, and initialize `DependencyTrackingTelemetryModule` as follows:
42+
43+
```csharp
44+
DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
45+
depModule.Initialize(TelemetryConfiguration.Active);
46+
```
47+
48+
### How automatic dependency monitoring works?
49+
50+
Dependencies are automatically collected by using one of the following techniques:
51+
52+
* Using byte code instrumentation around select methods. (InstrumentationEngine either from StatusMonitor or Azure Web App Extension)
53+
* EventSource callbacks
54+
* DiagnosticSource callbacks (in the latest .NET/.NET Core SDKs)
55+
56+
## Manually tracking dependencies
57+
58+
The following are some examples of dependencies, which aren't automatically collected, and hence require manual tracking.
59+
60+
* Azure Cosmos DB is tracked automatically only if [HTTP/HTTPS](../../cosmos-db/performance-tips.md#networking) is used. TCP mode won't be captured by Application Insights.
61+
* Redis
62+
63+
For those dependencies not automatically collected by SDK, you can track them manually using the [TrackDependency API](api-custom-events-metrics.md#trackdependency) that is used by the standard auto collection modules.
64+
65+
For example, if you build your code with an assembly that you didn't write yourself, you could time all the calls to it, to find out what contribution it makes to your response times. To have this data displayed in the dependency charts in Application Insights, send it using `TrackDependency`.
66+
67+
```csharp
68+
69+
var startTime = DateTime.UtcNow;
70+
var timer = System.Diagnostics.Stopwatch.StartNew();
71+
try
72+
{
73+
// making dependency call
74+
success = dependency.Call();
75+
}
76+
finally
77+
{
78+
timer.Stop();
79+
telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
80+
}
81+
```
82+
83+
Alternatively, `TelemetryClient` provides extension methods `StartOperation` and `StopOperation` which can be used to manually track dependencies, as shown [here](custom-operations-tracking.md#outgoing-dependencies-tracking)
84+
85+
If you want to switch off the standard dependency tracking module, remove the reference to DependencyTrackingTelemetryModule in [ApplicationInsights.config](../../azure-monitor/app/configuration-with-applicationinsights-config.md) for ASP.NET applications. For ASP.NET Core applications, follow instructions [here](asp-net-core.md#configuring-or-removing-default-telemetrymodules).
86+
87+
## Tracking AJAX calls from Web Pages
88+
89+
For web pages, Application Insights JavaScript SDK automatically collects AJAX calls as dependencies as described [here](javascript.md#ajax-performance). This document focuses on dependencies from server components.
90+
91+
## Advanced SQL tracking to get full SQL Query
92+
93+
For SQL calls, the name of the server and database is always collected and stored as name of the collected `DependencyTelemetry`. There's an additional field called 'data', which can contain the full SQL query text.
94+
95+
For ASP.NET Core applications, there's no additional step required to get the full SQL Query.
96+
97+
For ASP.NET applications, full SQL query is collected with the help of byte code instrumentation, which requires instrumentation engine. Additional platform-specific steps, as described below, are required.
98+
99+
| Platform | Step(s) Needed to get full SQL Query |
42100
| --- | --- |
43-
| IIS Server |Either [install Status Monitor on your server](../../azure-monitor/app/monitor-performance-live-website-now.md) or [Upgrade your application to .NET framework 4.6 or later](https://go.microsoft.com/fwlink/?LinkId=528259) and install the [Application Insights SDK](asp-net.md) in your app. |
44-
| Azure Web App |In your web app control panel, [open the Application Insights blade in your web app control panel](../../azure-monitor/app/azure-web-apps.md) and choose Install if prompted. |
45-
| Azure Cloud Service |[Use startup task](../../azure-monitor/app/cloudservices.md) or [Install .NET framework 4.6+](../../cloud-services/cloud-services-dotnet-install-dotnet.md) |
101+
| Azure Web App |In your web app control panel, [open the Application Insights blade](../../azure-monitor/app/azure-web-apps.md) and enable SQL Commands under .NET |
102+
| IIS Server (Azure VM, on-prem, and so on.) | [Install Status Monitor on your server where application is running](../../azure-monitor/app/monitor-performance-live-website-now.md) and restart IIS.
103+
| Azure Cloud Service |[Use startup task](../../azure-monitor/app/cloudservices.md) to [Install Status Monitor](monitor-performance-live-website-now.md#download) |
104+
| IIS Express | Not supported
105+
106+
In the above cases, the correct way of validating that instrumentation engine is correctly installed is by validating that the SDK version of collected `DependencyTelemetry` is 'rddp'. 'rdddsd' or 'rddf' indicates dependencies are collected via DiagnosticSource or EventSource callbacks, and hence full SQL query won't be captured.
46107

47108
## Where to find dependency data
109+
48110
* [Application Map](#application-map) visualizes dependencies between your app and neighboring components.
49-
* [Performance, browser, and failure blades](https://docs.microsoft.com/azure/azure-monitor/learn/tutorial-performance) show server dependency data.
111+
* [Performance, browser, and failure blades](#performance-and-failure-blades) show server dependency data.
50112
* [Browsers blade](#ajax-calls) shows AJAX calls from your users' browsers.
51113
* Click through from slow or failed requests to check their dependency calls.
52114
* [Analytics](#analytics) can be used to query dependency data.
53115

54116
## Application Map
117+
55118
Application Map acts as a visual aid to discovering dependencies between the components of your application. It is automatically generated from the telemetry from your app. This example shows AJAX calls from the browser scripts and REST calls from the server app to two external services.
56119

57-
![Application Map](./media/asp-net-dependencies/cloud-rolename.png)
120+
![Application Map](./media/asp-net-dependencies/08.png)
58121

59122
* **Navigate from the boxes** to relevant dependency and other charts.
60123
* **Pin the map** to the [dashboard](../../azure-monitor/app/app-insights-dashboards.md), where it will be fully functional.
61124

62125
[Learn more](../../azure-monitor/app/app-map.md).
63126

64127
## Performance and failure blades
65-
The performance blade shows the duration of dependency calls made by the server app.
66128

67-
**Failure counts** are shown on the **Failures** blade. A failure is any return code that is not in the range 200-399, or unknown.
129+
The performance blade shows the duration of dependency calls made by the server app. There's a summary chart and a table segmented by call.
130+
131+
![Performance blade dependency charts](./media/asp-net-dependencies/dependencies-in-performance-blade.png)
68132

69-
> [!NOTE]
70-
> **100% failures?** - This probably indicates that you are only getting partial dependency data. You need to [set up dependency monitoring appropriate to your platform](#set-up-dependency-monitoring).
71-
>
72-
>
133+
Click through the summary charts or the table items to search raw occurrences of these calls.
134+
135+
![Dependency call instances](./media/asp-net-dependencies/dependency-call-instance.png)
136+
137+
**Failure counts** are shown on the **Failures** blade. A failure is any return code that is not in the range 200-399, or unknown.
73138

74139
## AJAX Calls
140+
75141
The Browsers blade shows the duration and failure rate of AJAX calls from [JavaScript in your web pages](../../azure-monitor/app/javascript.md). They are shown as Dependencies.
76142

77143
## <a name="diagnosis"></a> Diagnose slow requests
78-
Each request event is associated with the dependency calls, exceptions, and other events that are tracked while your app is processing the request. So if some requests are performing badly, you can find out whether it's due to slow responses from a dependency.
144+
145+
Each request event is associated with the dependency calls, exceptions and other events that are tracked while your app is processing the request. So if some requests are doing badly, you can find out whether it's because of slow responses from a dependency.
146+
147+
Let's walk through an example of that.
148+
149+
### Tracing from requests to dependencies
150+
151+
Open the Performance blade, and look at the grid of requests:
152+
153+
![List of requests with averages and counts](./media/asp-net-dependencies/02-reqs.png)
154+
155+
The top one is taking long. Let's see if we can find out where the time is spent.
156+
157+
Click that row to see individual request events:
158+
159+
![List of request occurrences](./media/asp-net-dependencies/03-instances.png)
160+
161+
Click any long-running instance to inspect it further, and scroll down to the remote dependency calls related to this request:
162+
163+
![Find Calls to Remote Dependencies, identify unusual Duration](./media/asp-net-dependencies/04-dependencies.png)
164+
165+
It looks like most of the time servicing this request was spent in a call to a local service.
166+
167+
Select that row to get more information:
168+
169+
![Click through that remote dependency to identify the culprit](./media/asp-net-dependencies/05-detail.png)
170+
171+
Looks like this dependency is where the problem is. We've pinpointed the problem, so now we just need to find out why that call is taking so long.
172+
173+
### Request timeline
174+
175+
In a different case, there is no dependency call that is particularly long. But by switching to the timeline view, we can see where the delay occurred in our internal processing:
176+
177+
![Find Calls to Remote Dependencies, identify unusual Duration](./media/asp-net-dependencies/04-1.png)
178+
179+
There seems to be a large gap after the first dependency call, so we should look at our code to see why that is.
79180

80181
### Profile your live site
81182

82-
No idea where the time goes? The [Application Insights profiler](../../azure-monitor/app/profiler.md) traces HTTP calls to your live site and shows which functions in your code took the longest time.
183+
No idea where the time goes? The [Application Insights profiler](../../azure-monitor/app/profiler.md) traces HTTP calls to your live site and shows you the functions in your code that took the longest time.
184+
185+
## Failed requests
186+
187+
Failed requests might also be associated with failed calls to dependencies. Again, we can click through to track down the problem.
188+
189+
![Click the failed requests chart](./media/asp-net-dependencies/06-fail.png)
190+
191+
Click through to an occurrence of a failed request, and look at its associated events.
192+
193+
![Click a request type, click the instance to get to a different view of the same instance, click it to get exception details.](./media/asp-net-dependencies/07-faildetail.png)
83194

84195
## Analytics
196+
85197
You can track dependencies in the [Kusto query language](/azure/kusto/query/). Here are some examples.
86198

87199
* Find any failed dependency calls:
@@ -119,49 +231,22 @@ You can track dependencies in the [Kusto query language](/azure/kusto/query/). H
119231
on operation_Id
120232
```
121233

234+
## Video
122235

236+
> [!VIDEO https://channel9.msdn.com/events/Connect/2016/112/player]
123237
124-
## Custom dependency tracking
125-
The standard dependency-tracking module automatically discovers external dependencies such as databases and REST APIs. But you might want some additional components to be treated in the same way.
238+
## Frequently asked questions
126239

127-
You can write code that sends dependency information, using the same [TrackDependency API](../../azure-monitor/app/api-custom-events-metrics.md#trackdependency) that is used by the standard modules.
240+
### *How does automatic dependency collector report failed calls to dependencies?*
128241

129-
For example, if you build your code with an assembly that you didn't write yourself, you could time all the calls to it, to find out what contribution it makes to your response times. To have this data displayed in the dependency charts in Application Insights, send it using `TrackDependency`.
242+
* Failed dependency calls will have 'success' field set to False. `DependencyTrackingTelemetryModule` does not report `ExceptionTelemetry`. The full data model for dependency is described [here](data-model-dependency-telemetry.md).
130243

131-
```csharp
244+
## Open-source SDK
245+
Like every Application Insights SDK, dependency collection module is also open-source. Read and contribute to the code, or report issues at [the official GitHub repo](https://github.com/Microsoft/ApplicationInsights-dotnet-server).
132246

133-
var startTime = DateTime.UtcNow;
134-
var timer = System.Diagnostics.Stopwatch.StartNew();
135-
try
136-
{
137-
success = dependency.Call();
138-
}
139-
finally
140-
{
141-
timer.Stop();
142-
telemetry.TrackDependency("myDependency", "myCall", startTime, timer.Elapsed, success);
143-
// The call above has been made obsolete in the latest SDK. The updated call follows this format:
144-
// TrackDependency (string dependencyTypeName, string dependencyName, string data, DateTimeOffset startTime, TimeSpan duration, bool success);
145-
}
146-
```
147-
148-
If you want to switch off the standard dependency tracking module, remove the reference to DependencyTrackingTelemetryModule in [ApplicationInsights.config](../../azure-monitor/app/configuration-with-applicationinsights-config.md).
149-
150-
## Troubleshooting
151-
*Dependency success flag always shows either true or false.*
152-
153-
*SQL query not shown in full.*
154-
155-
Consult the table below and insure you have chosen the correct configuration to enable dependency monitoring for your application.
156-
157-
| Platform | Install |
158-
| --- | --- |
159-
| IIS Server |Either [install Status Monitor on your server](../../azure-monitor/app/monitor-performance-live-website-now.md). Or [Upgrade your application to .NET framework 4.6 or later](https://go.microsoft.com/fwlink/?LinkId=528259) and install the [Application Insights SDK](asp-net.md) in your app. |
160-
| IIS Express |Use IIS Server instead. |
161-
| Azure Web App |In your web app control panel, [open the Application Insights blade in your web app control panel](../../azure-monitor/app/azure-web-apps.md) and choose Install if prompted. |
162-
| Azure Cloud Service |[Use startup task](../../azure-monitor/app/cloudservices.md) or [Install .NET framework 4.6+](../../cloud-services/cloud-services-dotnet-install-dotnet.md). |
163247

164248
## Next steps
249+
165250
* [Exceptions](../../azure-monitor/app/asp-net-exceptions.md)
166251
* [User & page data](../../azure-monitor/app/javascript.md)
167252
* [Availability](../../azure-monitor/app/monitor-web-app-availability.md)

0 commit comments

Comments
 (0)