Opplæring
Læringsbane
Develop an instrumentation strategy - Training
Develop an effective instrumentation strategy through logging, telemetry, and monitoring and prepare for Exam AZ-400: Designing and Implementing Microsoft DevOps Solutions.
Denne nettleseren støttes ikke lenger.
Oppgrader til Microsoft Edge for å dra nytte av de nyeste funksjonene, sikkerhetsoppdateringene og den nyeste tekniske støtten.
This article shows you how to configure Azure Monitor Application Insights for Java.
For more information, see Get started with OpenTelemetry which includes sample applications.
Connection string and role name are the most common settings you need to get started:
{
"connectionString": "...",
"role": {
"name": "my cloud role name"
}
}
Connection string is required. Role name is important anytime you're sending data from different applications to the same Application Insights resource.
More information and configuration options are provided in the following sections.
By default, Application Insights Java 3 expects the configuration file to be named applicationinsights.json and located in the same directory as applicationinsights-agent-3.6.2.jar.
You can specify a custom configuration file with
If you provide a relative path, it will resolve relative to the directory where applicationinsights-agent-3.6.0.jar is located.
Instead of using a configuration file, you can set the entire JSON configuration with:
Connection string is required. You can find your connection string in your Application Insights resource.
{
"connectionString": "..."
}
You can also set the connection string by using the environment variable APPLICATIONINSIGHTS_CONNECTION_STRING
. It then takes precedence over the connection string specified in the JSON configuration.
Or you can set the connection string by using the Java system property applicationinsights.connection.string
. It also takes precedence over the connection string specified in the JSON configuration.
You can also set the connection string by specifying a file to load the connection string from.
If you specify a relative path, it resolves relative to the directory where applicationinsights-agent-3.6.2.jar
is located.
{
"connectionString": "${file:connection-string-file.txt}"
}
The file should contain only the connection string and nothing else.
Not setting the connection string disables the Java agent.
If you have multiple applications deployed in the same Java Virtual Machine (JVM) and want them to send telemetry to different connection strings, see Connection string overrides (preview).
The cloud role name is used to label the component on the application map.
If you want to set the cloud role name:
{
"role": {
"name": "my cloud role name"
}
}
If the cloud role name isn't set, the Application Insights resource's name is used to label the component on the application map.
You can also set the cloud role name by using the environment variable APPLICATIONINSIGHTS_ROLE_NAME
. It then takes precedence over the cloud role name specified in the JSON configuration.
Or you can set the cloud role name by using the Java system property applicationinsights.role.name
. It also takes precedence over the cloud role name specified in the JSON configuration.
If you have multiple applications deployed in the same JVM and want them to send telemetry to different cloud role names, see Cloud role name overrides (preview).
The cloud role instance defaults to the machine name.
If you want to set the cloud role instance to something different rather than the machine name:
{
"role": {
"name": "my cloud role name",
"instance": "my cloud role instance"
}
}
You can also set the cloud role instance by using the environment variable APPLICATIONINSIGHTS_ROLE_INSTANCE
. It then takes precedence over the cloud role instance specified in the JSON configuration.
Or you can set the cloud role instance by using the Java system property applicationinsights.role.instance
.
It also takes precedence over the cloud role instance specified in the JSON configuration.
Obs!
Sampling can be a great way to reduce the cost of Application Insights. Make sure to set up your sampling configuration appropriately for your use case.
Sampling is based on request, which means that if a request is captured (sampled), so are its dependencies, logs, and exceptions.
Sampling is also based on trace ID to help ensure consistent sampling decisions across different services.
Sampling only applies to logs inside of a request. Logs that aren't inside of a request (for example, startup logs) are always collected by default. If you want to sample those logs, you can use Sampling overrides.
Starting from 3.4.0, rate-limited sampling is available and is now the default.
If no sampling is configured, the default is now rate-limited sampling configured to capture at most (approximately) five requests per second, along with all the dependencies and logs on those requests.
This configuration replaces the prior default, which was to capture all requests. If you still want to capture all requests, use fixed-percentage sampling and set the sampling percentage to 100.
Obs!
The rate-limited sampling is approximate because internally it must adapt a "fixed" sampling percentage over time to emit accurate item counts on each telemetry record. Internally, the rate-limited sampling is tuned to adapt quickly (0.1 seconds) to new application loads. For this reason, you shouldn't see it exceed the configured rate by much, or for very long.
This example shows how to set the sampling to capture at most (approximately) one request per second:
{
"sampling": {
"requestsPerSecond": 1.0
}
}
The requestsPerSecond
can be a decimal, so you can configure it to capture less than one request per second if you want. For example, a value of 0.5
means capture at most one request every 2 seconds.
You can also set the sampling percentage by using the environment variable APPLICATIONINSIGHTS_SAMPLING_REQUESTS_PER_SECOND
. It then takes precedence over the rate limit specified in the JSON configuration.
This example shows how to set the sampling to capture approximately a third of all requests:
{
"sampling": {
"percentage": 33.333
}
}
You can also set the sampling percentage by using the environment variable APPLICATIONINSIGHTS_SAMPLING_PERCENTAGE
. It then takes precedence over the sampling percentage specified in the JSON configuration.
Obs!
For the sampling percentage, choose a percentage that's close to 100/N, where N is an integer. Currently, sampling doesn't support other values.
Sampling overrides allow you to override the default sampling percentage. For example, you can:
/login
even though you have the default sampling configured to something lower.For more information, see the Sampling overrides documentation.
If you want to collect some other Java Management Extensions (JMX) metrics:
{
"jmxMetrics": [
{
"name": "JVM uptime (millis)",
"objectName": "java.lang:type=Runtime",
"attribute": "Uptime"
},
{
"name": "MetaSpace Used",
"objectName": "java.lang:type=MemoryPool,name=Metaspace",
"attribute": "Usage.used"
}
]
}
In the preceding configuration example:
name
is the metric name that is assigned to this JMX metric (can be anything).objectName
is the Object Name of the JMX MBean
that you want to collect. Wildcard character asterisk (*) is supported.attribute
is the attribute name inside of the JMX MBean
that you want to collect.Numeric and Boolean JMX metric values are supported. Boolean JMX metrics are mapped to 0
for false and 1
for true.
For more information, see the JMX metrics documentation.
If you want to add custom dimensions to all your telemetry:
{
"customDimensions": {
"mytag": "my value",
"anothertag": "${ANOTHER_VALUE}"
}
}
You can use ${...}
to read the value from the specified environment variable at startup.
Obs!
Starting from version 3.0.2, if you add a custom dimension named service.version
, the value is stored in the application_Version
column in the Application Insights Logs table instead of as a custom dimension.
Starting with version 3.2.0, you can set a custom dimension programmatically on your request telemetry. It ensures inheritance by dependency and log telemetry. All are captured in the context of that request.
{
"preview": {
"inheritedAttributes": [
{
"key": "mycustomer",
"type": "string"
}
]
}
}
And then at the beginning of each request, call:
Span.current().setAttribute("mycustomer", "xyz");
Also see: Add a custom property to a Span.
This feature is in preview, starting from 3.4.0.
Connection string overrides allow you to override the default connection string. For example, you can:
/myapp1
./myapp2/
.{
"preview": {
"connectionStringOverrides": [
{
"httpPathPrefix": "/myapp1",
"connectionString": "..."
},
{
"httpPathPrefix": "/myapp2",
"connectionString": "..."
}
]
}
}
This feature is in preview, starting from 3.3.0.
Cloud role name overrides allow you to override the default cloud role name. For example, you can:
/myapp1
./myapp2/
.{
"preview": {
"roleNameOverrides": [
{
"httpPathPrefix": "/myapp1",
"roleName": "Role A"
},
{
"httpPathPrefix": "/myapp2",
"roleName": "Role B"
}
]
}
}
Starting from version 3.4.8, if you need the ability to configure the connection string at runtime, add this property to your json configuration:
{
"connectionStringConfiguredAtRuntime": true
}
Add applicationinsights-core
to your application:
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>applicationinsights-core</artifactId>
<version></version>
</dependency>
Use the static configure(String)
method in the class
com.microsoft.applicationinsights.connectionstring.ConnectionString
.
Obs!
Any telemetry that is captured prior to configuring the connection string will be dropped, so it is best to configure it as early as possible in your application startup.
Starting from version 3.2.0, if you want to capture controller "InProc" dependencies, use the following configuration:
{
"preview": {
"captureControllerSpans": true
}
}
This feature automatically injects the Browser SDK Loader into your application's HTML pages, including configuring the appropriate Connection String.
For example, when your java application returns a response like:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Title</title>
</head>
<body>
</body>
</html>
It automatically modifies to return:
<!DOCTYPE html>
<html lang="en">
<head>
<script type="text/javascript">
!function(v,y,T){var S=v.location,k="script"
<!-- Removed for brevity -->
connectionString: "YOUR_CONNECTION_STRING"
<!-- Removed for brevity --> }});
</script>
<title>Title</title>
</head>
<body>
</body>
</html>
The script is aiming at helping customers to track the web user data, and sent the collecting server-side telemetry back to users' Azure portal. Details can be found at ApplicationInsights-JS.
If you want to enable this feature, add the below configuration option:
{
"preview": {
"browserSdkLoader": {
"enabled": true
}
}
}
You can use telemetry processors to configure rules that are applied to request, dependency, and trace telemetry. For example, you can:
For more information, see the Telemetry processor documentation.
Obs!
If you want to drop specific (whole) spans for controlling ingestion cost, see Sampling overrides.
Starting from verion 3.3.1, you can capture spans for a method in your application:
{
"preview": {
"customInstrumentation": [
{
"className": "my.package.MyClass",
"methodName": "myMethod"
}
]
}
}
By default, when the effective sampling percentage in the Java agent is 100% and ingestion sampling has been configured on your Application Insights resource, then the ingestion sampling percentage will be applied.
Note that this behavior applies to both fixed-rate sampling of 100% and also applies to rate-limited sampling when the request rate doesn't exceed the rate limit (effectively capturing 100% during the continuously sliding time window).
Starting from 3.5.3, you can disable this behavior (and keep 100% of telemetry in these cases even when ingestion sampling has been configured on your Application Insights resource):
{
"preview": {
"sampling": {
"ingestionSamplingEnabled": false
}
}
}
Log4j, Logback, JBoss Logging, and java.util.logging are autoinstrumented. Logging performed via these logging frameworks is autocollected.
Logging is only captured if it:
For example, if your logging framework is configured to log WARN
(and you configured it as described earlier) from the package com.example
,
and Application Insights is configured to capture INFO
(and you configured as described), Application Insights only captures WARN
(and more severe) from the package com.example
.
The default level configured for Application Insights is INFO
. If you want to change this level:
{
"instrumentation": {
"logging": {
"level": "WARN"
}
}
}
You can also set the level by using the environment variable APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL
. It then takes precedence over the level specified in the JSON configuration.
You can use these valid level
values to specify in the applicationinsights.json
file. The table shows how they correspond to logging levels in different logging frameworks.
Level | Log4j | Logback | JBoss | JUL |
---|---|---|---|---|
OFF | OFF | OFF | OFF | OFF |
FATAL | FATAL | ERROR | FATAL | SEVERE |
ERROR (or SEVERE) | ERROR | ERROR | ERROR | SEVERE |
WARN (or WARNING) | WARN | WARN | WARN | WARNING |
INFO | INFO | INFO | INFO | INFO |
CONFIG | DEBUG | DEBUG | DEBUG | CONFIG |
DEBUG (or FINE) | DEBUG | DEBUG | DEBUG | FINE |
FINER | DEBUG | DEBUG | DEBUG | FINER |
TRACE (or FINEST) | TRACE | TRACE | TRACE | FINEST |
ALL | ALL | ALL | ALL | ALL |
Obs!
If an exception object is passed to the logger, the log message (and exception object details) will show up in the Azure portal under the exceptions
table instead of the traces
table. If you want to see the log messages across both the traces
and exceptions
tables, you can write a Logs (Kusto) query to union across them. For example:
union traces, (exceptions | extend message = outerMessage)
| project timestamp, message, itemType
Starting from 3.4.2, you can capture the log markers for Logback and Log4j 2:
{
"preview": {
"captureLogbackMarker": true,
"captureLog4jMarker": true
}
}
Starting from 3.4.3, you can capture FileName
, ClassName
, MethodName
, and LineNumber
, for Logback:
{
"preview": {
"captureLogbackCodeAttributes": true
}
}
Advarsel
Capturing code attributes might add a performance overhead.
Starting from version 3.3.0, LoggingLevel
isn't captured by default as part of the Traces custom dimension because that data is already captured in the SeverityLevel
field.
If needed, you can temporarily re-enable the previous behavior:
{
"preview": {
"captureLoggingLevelAsCustomDimension": true
}
}
If your application uses Micrometer, metrics that are sent to the Micrometer global registry are autocollected.
Also, if your application uses Spring Boot Actuator, metrics configured by Spring Boot Actuator are also autocollected.
To send custom metrics using micrometer:
Add Micrometer to your application as shown in the following example.
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-core</artifactId>
<version>1.6.1</version>
</dependency>
Use the Micrometer global registry to create a meter as shown in the following example.
static final Counter counter = Metrics.counter("test.counter");
Use the counter to record metrics by using the following command.
counter.increment();
The metrics are ingested into the
customMetrics table, with tags captured in the
customDimensions
column. You can also view the metrics in the
metrics explorer under the Log-based metrics
metric namespace.
Obs!
Application Insights Java replaces all non-alphanumeric characters (except dashes) in the Micrometer metric name with underscores. As a result, the preceding test.counter
metric will show up as test_counter
.
To disable autocollection of Micrometer metrics and Spring Boot Actuator metrics:
Obs!
Custom metrics are billed separately and might generate extra costs. Make sure to check the Pricing information. To disable the Micrometer and Spring Boot Actuator metrics, add the following configuration to your config file.
{
"instrumentation": {
"micrometer": {
"enabled": false
}
}
}
Literal values in Java Database Connectivity (JDBC) queries are masked by default to avoid accidentally capturing sensitive data.
Starting from 3.4.0, this behavior can be disabled. For example:
{
"instrumentation": {
"jdbc": {
"masking": {
"enabled": false
}
}
}
}
Literal values in Mongo queries are masked by default to avoid accidentally capturing sensitive data.
Starting from 3.4.0, this behavior can be disabled. For example:
{
"instrumentation": {
"mongo": {
"masking": {
"enabled": false
}
}
}
}
Starting from version 3.3.0, you can capture request and response headers on your server (request) telemetry:
{
"preview": {
"captureHttpServerHeaders": {
"requestHeaders": [
"My-Header-A"
],
"responseHeaders": [
"My-Header-B"
]
}
}
}
The header names are case insensitive.
The preceding examples are captured under the property names http.request.header.my_header_a
and
http.response.header.my_header_b
.
Similarly, you can capture request and response headers on your client (dependency) telemetry:
{
"preview": {
"captureHttpClientHeaders": {
"requestHeaders": [
"My-Header-C"
],
"responseHeaders": [
"My-Header-D"
]
}
}
}
Again, the header names are case insensitive. The preceding examples are captured under the property names
http.request.header.my_header_c
and http.response.header.my_header_d
.
By default, HTTP server requests that result in 4xx response codes are captured as errors.
Starting from version 3.3.0, you can change this behavior to capture them as success:
{
"preview": {
"captureHttpServer4xxAsError": false
}
}
Starting from version 3.0.3, specific autocollected telemetry can be suppressed by using these configuration options:
{
"instrumentation": {
"azureSdk": {
"enabled": false
},
"cassandra": {
"enabled": false
},
"jdbc": {
"enabled": false
},
"jms": {
"enabled": false
},
"kafka": {
"enabled": false
},
"logging": {
"enabled": false
},
"micrometer": {
"enabled": false
},
"mongo": {
"enabled": false
},
"quartz": {
"enabled": false
},
"rabbitmq": {
"enabled": false
},
"redis": {
"enabled": false
},
"springScheduling": {
"enabled": false
}
}
}
You can also suppress these instrumentations by setting these environment variables to false
:
APPLICATIONINSIGHTS_INSTRUMENTATION_AZURE_SDK_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_CASSANDRA_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_JDBC_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_JMS_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_KAFKA_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_MICROMETER_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_MONGO_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_RABBITMQ_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_REDIS_ENABLED
APPLICATIONINSIGHTS_INSTRUMENTATION_SPRING_SCHEDULING_ENABLED
These variables then take precedence over the enabled variables specified in the JSON configuration.
Obs!
If you're looking for more fine-grained control, for example, to suppress some redis calls but not all redis calls, see Sampling overrides.
Starting from version 3.2.0, you can enable the following preview instrumentations:
{
"preview": {
"instrumentation": {
"akka": {
"enabled": true
},
"apacheCamel": {
"enabled": true
},
"grizzly": {
"enabled": true
},
"ktor": {
"enabled": true
},
"play": {
"enabled": true
},
"r2dbc": {
"enabled": true
},
"springIntegration": {
"enabled": true
},
"vertx": {
"enabled": true
}
}
}
}
Obs!
Akka instrumentation is available starting from version 3.2.2. Vertx HTTP Library instrumentation is available starting from version 3.3.0.
By default, metrics are captured every 60 seconds.
Starting from version 3.0.3, you can change this interval:
{
"metricIntervalSeconds": 300
}
Starting from 3.4.9 GA, you can also set the metricIntervalSeconds
by using the environment variable APPLICATIONINSIGHTS_METRIC_INTERVAL_SECONDS
. It then takes precedence over the metricIntervalSeconds
specified in the JSON configuration.
The setting applies to the following metrics:
By default, Application Insights Java 3.x sends a heartbeat metric once every 15 minutes. If you're using the heartbeat metric to trigger alerts, you can increase the frequency of this heartbeat:
{
"heartbeat": {
"intervalSeconds": 60
}
}
Obs!
You can't increase the interval to longer than 15 minutes because the heartbeat data is also used to track Application Insights usage.
Obs!
The authentication feature is GA since version 3.4.17.
You can use authentication to configure the agent to generate token credentials that are required for Microsoft Entra authentication. For more information, see the Authentication documentation.
If your application is behind a firewall and can't connect directly to Application Insights, refer to IP addresses used by Application Insights.
To work around this issue, you can configure Application Insights Java 3.x to use an HTTP proxy.
{
"proxy": {
"host": "myproxy",
"port": 8080
}
}
You can also set the http proxy using the environment variable APPLICATIONINSIGHTS_PROXY
, which takes the format https://<host>:<port>
. It then takes precedence over the proxy specified in the JSON configuration.
You can provide a user and a password for your proxy with the APPLICATIONINSIGHTS_PROXY
environment variable: https://<user>:<password>@<host>:<port>
.
Application Insights Java 3.x also respects the global https.proxyHost
and https.proxyPort
system properties if they're set, and http.nonProxyHosts
, if needed.
When sending telemetry to the Application Insights service fails, Application Insights Java 3.x stores the telemetry to disk and continues retrying from disk.
The default limit for disk persistence is 50 Mb. If you have high telemetry volume or need to be able to recover from longer network or ingestion service outages, you can increase this limit starting from version 3.3.0:
{
"preview": {
"diskPersistenceMaxSizeMb": 50
}
}
"Self-diagnostics" refers to internal logging from Application Insights Java 3.x. This functionality can be helpful for spotting and diagnosing issues with Application Insights itself.
By default, Application Insights Java 3.x logs at level INFO
to both the file applicationinsights.log
and the console, corresponding to this configuration:
{
"selfDiagnostics": {
"destination": "file+console",
"level": "INFO",
"file": {
"path": "applicationinsights.log",
"maxSizeMb": 5,
"maxHistory": 1
}
}
}
In the preceding configuration example:
level
can be one of OFF
, ERROR
, WARN
, INFO
, DEBUG
, or TRACE
.path
can be an absolute or relative path. Relative paths are resolved against the directory where
applicationinsights-agent-3.6.2.jar
is located.Starting from version 3.0.2, you can also set the self-diagnostics level
by using the environment variable
APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL
. It then takes precedence over the self-diagnostics level specified in the JSON configuration.
Starting from version 3.0.3, you can also set the self-diagnostics file location by using the environment variable APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_FILE_PATH
. It then takes precedence over the self-diagnostics file path specified in the JSON configuration.
Telemetry correlation is enabled by default, but you may disable it in configuration.
{
"preview": {
"disablePropagation": true
}
}
This example shows what a configuration file looks like with multiple components. Configure specific options based on your needs.
{
"connectionString": "...",
"role": {
"name": "my cloud role name"
},
"sampling": {
"percentage": 100
},
"jmxMetrics": [
],
"customDimensions": {
},
"instrumentation": {
"logging": {
"level": "INFO"
},
"micrometer": {
"enabled": true
}
},
"proxy": {
},
"preview": {
"processors": [
]
},
"selfDiagnostics": {
"destination": "file+console",
"level": "INFO",
"file": {
"path": "applicationinsights.log",
"maxSizeMb": 5,
"maxHistory": 1
}
}
}
Opplæring
Læringsbane
Develop an instrumentation strategy - Training
Develop an effective instrumentation strategy through logging, telemetry, and monitoring and prepare for Exam AZ-400: Designing and Implementing Microsoft DevOps Solutions.