你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

配置选项：适用于 Java 的 Azure Monitor Application Insights

本文介绍如何配置适用于 Java 的 Azure Monitor Application Insights。

连接字符串和角色名称

连接字符串和角色名称是开始使用该服务所需的最常见设置：

{
  "connectionString": "...",
  "role": {
    "name": "my cloud role name"
  }
}

连接字符串是必需的。 每次将数据从不同的应用程序发送到相同的 Application Insights 资源时，角色名称都非常重要。

以下部分提供了详细信息和配置选项。

配置文件路径

默认情况下，Application Insights Java 3.X 要求将配置文件命名为 applicationinsights.json，并置于 applicationinsights-agent-3.5.1.jar 所在的目录中。

可以使用以下两个选项之一指定你自己的配置文件路径：

• APPLICATIONINSIGHTS_CONFIGURATION_FILE 环境变量
• applicationinsights.configuration.file Java 系统属性

如果你指定相对路径，系统会相对于 applicationinsights-agent-3.5.1.jar 所在的目录对其进行解析。

或者，你可以通过环境变量 APPLICATIONINSIGHTS_CONFIGURATION_CONTENT 指定 JSON 配置的全部内容，而不是使用配置文件。

连接字符串

连接字符串是必需的。 可以在 Application Insights 资源中找到连接字符串。

{
  "connectionString": "..."
}

还可以使用环境变量 APPLICATIONINSIGHTS_CONNECTION_STRING 设置连接字符串。 它优先于 JSON 配置中指定的连接字符串。

或者，可以使用 Java 系统属性 applicationinsights.connection.string 设置连接字符串。 它还优先于 JSON 配置中指定的连接字符串。

还可以通过指定要从中加载连接字符串的文件来设置连接字符串。

如果你指定相对路径，系统会相对于 applicationinsights-agent-3.5.1.jar 所在的目录对其进行解析。

{
  "connectionString": "${file:connection-string-file.txt}"
}

文件应只包含连接字符串，不能包含其他内容。

如果未设置连接字符串，则将禁用 Java 代理。

如果多个应用程序部署在同一 Java 虚拟机 (JVM) 中，并希望将遥测数据发送到不同的连接字符串，请参阅连接字符串替代（预览版）。

云角色名称

云角色名称用于标记应用程序映射上的组件。

如果要设置云角色名称，请执行以下代码：

{
  "role": {   
    "name": "my cloud role name"
  }
}

如果你未设置云角色名称，系统会使用 Application Insights 资源的名称在应用程序映射上标记该组件。

还可以使用环境变量 APPLICATIONINSIGHTS_ROLE_NAME 设置云角色名称。 它优先于 JSON 配置中指定的云角色名称。

或者，可以使用 Java 系统属性 applicationinsights.role.name 设置云角色名称。 它也优先于 JSON 配置中指定的云角色名称。

如果在同一 JVM 中部署了多个应用程序，并希望它们将遥测数据发送到不同的云角色名称，请参阅云角色名称替代（预览版）。

云角色实例

云角色实例默认为计算机名称。

若要将云角色实例设置为不同于计算机名称的名称，请执行以下代码：

{
  "role": {
    "name": "my cloud role name",
    "instance": "my cloud role instance"
  }
}

还可以使用环境变量 APPLICATIONINSIGHTS_ROLE_INSTANCE 设置云角色实例。 它优先于 JSON 配置中指定的云角色实例。

或者，可以使用 Java 系统属性 applicationinsights.role.instance 设置云角色实例。 它也优先于 JSON 配置中指定的云角色实例。

采样

备注

采样是降低 Application Insights 成本的好方法。 请确保为用例正确设置采样配置。

采样基于请求，这意味着，如果捕获（采样）了某个请求，也会捕获（采样）该请求的依赖项、日志和异常。

采样还基于跟踪 ID，有助于确保跨不同服务做出一致的采样决策。

采样仅适用于请求中的日志。 默认情况下，始终收集不在请求内的日志（例如启动日志）。 如果要对这些日志进行采样，可以使用采样替代。

速率限制采样

自 3.4.0 起开始提供速率限制采样，现在为默认设置。

如果尚未配置采样，则现在默认采用配置为每秒最多捕获（大约）5 个请求以及这些请求的所有依赖项和日志的速率限制采样。

此配置取代了以前的默认值，即捕获所有请求。 如果仍希望捕获所有请求，请使用固定百分比采样并将采样百分比设置为 100。

注意

比率限制采样是近似的，因为在内部它必须随时间调整一个“固定”采样百分比，以便在每个遥测记录上发出准确的项计数。 在内部，比率限制采样经过优化以快速（0.1 秒）适应新的应用程序负载。 出于此原因，它应该不会超过配置的比率太多，也不会花费太长时间。

以下示例演示如何将采样设置为每秒最多捕获（大约）1 个请求：

{
  "sampling": {
    "requestsPerSecond": 1.0
  }
}

requestsPerSecond 可以是小数，因此可以根据需要将其配置为每秒捕获少于 1 个请求。 例如，值 0.5 表示每 2 秒最多捕获 1 个请求。

还可以使用环境变量 APPLICATIONINSIGHTS_SAMPLING_REQUESTS_PER_SECOND 设置采样百分比。 它优先于 JSON 配置中指定的比率限制。

固定百分比采样

以下示例演示如何设置采样以捕获大约三分之一的所有请求：

{
  "sampling": {
    "percentage": 33.333
  }
}

还可以使用环境变量 APPLICATIONINSIGHTS_SAMPLING_PERCENTAGE 设置采样百分比。 它优先于 JSON 配置中指定的采样百分比。

注意

对于采样百分比，请选择一个接近于 100/N 的百分比，其中 N 是整数。 当前采样不支持其他值。

采样替代

可以使用采样替代来替代默认采样百分比。 例如，你能够：

• 将采样百分比设置为 0（或某个小值）以检查干扰运行状况。
• 将采样百分比设置为 0（或一些小值）以调用干扰依赖项。
• 将重要请求类型的采样百分比设置为 100。 例如，即使已将默认采样配置为较低的值，也可以使用 /login。

有关详细信息，请参阅采样替代文档。

Java 管理扩展指标

如果要收集其他一些 Java 管理扩展 (JMX) 指标：

{
  "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"
    }
  ]
}

在前面的配置示例中：

• name 是将分配给此 JMX 指标的指标名称（可以是任何名称）。
• objectName 是要收集的 JMX MBean 的对象名称。 支持通配符星号 (*)。
• attribute 是要收集的 JMX MBean 内部的属性名称。

支持数值和布尔 JMX 指标值。 False 表示布尔 JMX 指标映射到 0，true 表示映射到 1。

有关更多详细信息，请参阅 JMX 指标文档。

自定义维度

如果要向所有遥测数据添加自定义维度：

{
  "customDimensions": {
    "mytag": "my value",
    "anothertag": "${ANOTHER_VALUE}"
  }
}

在启动时可以使用 ${...} 从指定的环境变量中读取值。

注意

从 3.0.2 版开始，如果你添加名为 service.version 的自定义维度，该值将存储在 Application Insights 日志表的 application_Version 列中，而不是作为自定义维度。

继承的属性（预览版）

从版本 3.2.0 开始，可以在请求遥测上以编程方式设置自定义维度。 它通过依赖项和日志遥测来确保继承。 所有内容都将在该请求的上下文中捕获。

{
  "preview": {
    "inheritedAttributes": [
      {
        "key": "mycustomer",
        "type": "string"
      }
    ]
  }
}

然后在每个请求开始时调用：

Span.current().setAttribute("mycustomer", "xyz");

另请参阅：将自定义属性添加到范围。

连接字符串替代（预览版）

此功能为预览版，从 3.4.0 开始提供。

连接字符串替代允许替代默认连接字符串。 例如，你能够：

• 为一个 HTTP 路径前缀 /myapp1 设置一个连接字符串。
• 为另一个 HTTP 路径前缀 /myapp2/ 设置另一个连接字符串。

{
  "preview": {
    "connectionStringOverrides": [
      {
        "httpPathPrefix": "/myapp1",
        "connectionString": "..."
      },
      {
        "httpPathPrefix": "/myapp2",
        "connectionString": "..."
      }
    ]
  }
}

云角色名称替代（预览版）

此功能为预览版，从 3.3.0 开始提供。

可以使用云角色名称替代来替代默认云角色名称。 例如，你能够：

• 为一个 HTTP 路径前缀 /myapp1 设置一个云角色名称。
• 为另一个 HTTP 路径前缀 /myapp2/ 设置另一个云角色名称。

{
  "preview": {
    "roleNameOverrides": [
      {
        "httpPathPrefix": "/myapp1",
        "roleName": "Role A"
      },
      {
        "httpPathPrefix": "/myapp2",
        "roleName": "Role B"
      }
    ]
  }
}

在运行时配置的连接字符串

从版本 3.4.8 开始，如果需要能够在运行时配置连接字符串，请将此属性添加到 json 配置：

{
  "connectionStringConfiguredAtRuntime": true
}

向应用程序添加 applicationinsights-core：

<dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>3.5.1</version>
</dependency>

在 com.microsoft.applicationinsights.connectionstring.ConnectionString 类中使用静态 configure(String) 方法。

注意

在配置连接字符串之前捕获的任何遥测都将被删除，因此最好在应用程序启动时尽早对其进行配置。

Autocollect InProc 依赖项（预览版）

从版本 3.2.0 开始，如果要捕获控制器“InProc”依赖项，请使用以下配置：

{
  "preview": {
    "captureControllerSpans": true
  }
}

浏览器 SDK 加载程序（预览版）

此功能会将浏览器 SDK 加载程序自动注入应用程序的 HTML 页面，包括配置相应的连接字符串。

例如，当 Java 应用程序返回如下响应时：

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Title</title>
  </head>
  <body>
  </body>
</html>

它会自动修改以返回：

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

该脚本旨在帮助客户跟踪 Web 用户数据，并将收集的服务器端遥测数据发送回用户的 Azure 门户。 有关详细信息，请参阅 ApplicationInsights-JS。

如果要启用此功能，请添加以下配置选项：

{
  "preview": {
    "browserSdkLoader": {
      "enabled": true
    }
  }
}

遥测处理器（预览版）

可以使用遥测处理器配置应用于请求、依赖项和跟踪遥测的规则。 例如，可以：

• 屏蔽敏感数据。
• 有条件地添加自定义维度。
• 更新用于在 Azure 门户中聚合类似遥测数据的范围名称。
• 删除范围属性以控制数据引入成本。

有关详细信息，请参阅遥测处理器文档。

注意

如果希望删除特定（整体）范围来控制数据引入成本，请参阅采样替代。

自动收集的日志记录

将自动检测 Log4j、Logback、JBoss Logging 和 java.util.logging。 将自动收集通过这些日志记录框架执行的日志记录。

仅在以下情况下捕获日志记录：

• 符合为记录框架的配置级别。
• 同时符合 Application Insights 的配置级别。

例如，如果将记录框架配置为从包 com.example 记录 WARN（并按前面所述配置），并将 Application Insights 配置为捕获 INFO（并按照描述配置），则 Application Insights 仅从包 com.example 捕获 WARN（以及更严重的级别）。

为 Application Insights 配置的默认级别为 INFO。 若要更改此级别，请执行以下代码：

{
  "instrumentation": {
    "logging": {
      "level": "WARN"
    }
  }
}

还可以使用环境变量 APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL 设置级别。 它优先于 JSON 配置中指定的级别。

可以在 applicationinsights.json 文件中使用这些有效的 level 值。 该表显示了它们如何对应于不同日志记录框架中的日志级别。

级别	Log4j	Logback	JBoss	JUL
OFF	OFF	OFF	OFF	OFF
FATAL	FATAL	ERROR	FATAL	SEVERE
ERROR（或 SEVERE）	ERROR	ERROR	ERROR	SEVERE
WARN（或 WARNING）	WARN	WARN	WARN	WARNING
INFO	INFO	INFO	INFO	INFO
CONFIG	DEBUG	DEBUG	DEBUG	CONFIG
DEBUG（或 FINE）	DEBUG	DEBUG	DEBUG	FINE
FINER	DEBUG	DEBUG	DEBUG	FINER
TRACE（或 FINEST）	TRACE	TRACE	TRACE	FINEST
ALL	ALL	ALL	ALL	ALL

注意

如果将异常对象传递到记录器，则日志消息（和异常对象详细信息）会显示在 Azure 门户中的 exceptions 表（而不是 traces 表）下。 如果想要查看 traces 和 exceptions 表中的日志消息，可以编写一个 Logs (Kusto) 查询来在这两个表之间进行联合。 例如：

union traces, (exceptions | extend message = outerMessage)
| project timestamp, message, itemType

日志标记（预览版）

从 3.4.2 开始，可以捕获 Logback 和 Log4j 2 的日志标记：

{
  "preview": {
    "captureLogbackMarker":  true,
    "captureLog4jMarker":  true
  }
}

Logback 的其他日志属性（预览版）

从 3.4.3 开始，可以捕获 Logback 的 FileName、ClassName、MethodName 和 LineNumber：

{
  "preview": {
    "captureLogbackCodeAttributes": true
  }
}

警告

捕获代码属性可能会增加性能开销。

作为自定义维度的日志记录级别

从版本 3.3.0 开始，LoggingLevel 在默认情况下不会作为跟踪的自定义维度的组成部分被捕获，因为该数据已在 SeverityLevel 字段中被捕获。

如果需要，可以暂时重新启用以前的行为：

{
  "preview": {
    "captureLoggingLevelAsCustomDimension": true
  }
}

自动收集的 Micrometer 指标（包括 Spring Boot Actuator 指标）

如果应用程序使用 Micrometer，则系统会自动收集发送到 Micrometer 全局注册表的指标。

此外，如果应用程序使用 Spring Boot Actuator，则系统也会自动收集 Spring Boot Actuator 配置的指标。

使用 Micrometer 发送自定义指标：

1. 将 Micrometer 添加到应用程序，如以下示例所示。

   <dependency>
     <groupId>io.micrometer</groupId>
     <artifactId>micrometer-core</artifactId>
     <version>1.6.1</version>
   </dependency>
   

2. 使用 Micrometer 全局注册表来创建计量，如以下示例所示。

   static final Counter counter = Metrics.counter("test.counter");
   

3. 使用计数器通过以下命令记录指标。

   counter.increment();
   

4. 这些指标将引入到 customMetrics 表中，带有在 customDimensions 列中捕获的标记。 还可以在 Log-based metrics 指标命名空间下的指标资源管理器中查看指标。

   注意

   Application Insights Java 将 Micrometer 指标名称中的所有非字母数字字符（短划线除外）替换为下划线。 因此，前面的 test.counter 指标将显示为 test_counter。

若要禁用自动收集 Micrometer 指标和 Spring Boot Actuator 指标，请运行以下命令：

注意

自定义指标单独计费，可能会产生额外的费用。 请务必查看定价信息。 若要禁用 Micrometer 和 Spring Boot Actuator 指标，请将以下配置添加到配置文件中。

{
  "instrumentation": {
    "micrometer": {
      "enabled": false
    }
  }
}

Java Database Connectivity 查询掩码

Java Database Connectivity (JDBC) 查询中的文本值默认进行掩码处理，以避免意外捕获敏感数据。

从 3.4.0 开始，可以禁用此行为。 例如：

{
  "instrumentation": {
    "jdbc": {
      "masking": {
        "enabled": false
      }
    }
  }
}

Mongo 查询掩码），

默认情况下，Mongo 查询中的文字值会掩码，以避免意外捕获敏感数据。

从 3.4.0 开始，可以禁用此行为。 例如：

{
  "instrumentation": {
    "mongo": {
      "masking": {
        "enabled": false
      }
    }
  }
}

HTTP 标头

从版本 3.3.0 开始，可以在服务器（请求）遥测上捕获请求和响应头：

{
  "preview": {
    "captureHttpServerHeaders": {
      "requestHeaders": [
        "My-Header-A"
      ],
      "responseHeaders": [
        "My-Header-B"
      ]
    }
  }
}

标头名称不区分大小写。

以上示例是在属性名称 http.request.header.my_header_a 和 http.response.header.my_header_b 下捕获的。

同样，你可以在客户端（依赖项）遥测上捕获请求和响应头：

{
  "preview": {
    "captureHttpClientHeaders": {
      "requestHeaders": [
        "My-Header-C"
      ],
      "responseHeaders": [
        "My-Header-D"
      ]
    }
  }
}

同样，标头名称不区分大小写。 以上示例是在属性名称 http.request.header.my_header_c 和 http.response.header.my_header_d 下捕获的。

HTTP 服务器 4xx 响应代码

默认情况下，导致出现 4xx 响应代码的 HTTP 服务器请求被捕获为错误。

从版本 3.3.0 开始，可以更改此行为，以将其捕获为成功：

{
  "preview": {
    "captureHttpServer4xxAsError": false
  }
}

取消特定的自动收集遥测

从版本 3.0.3 开始，可使用以下配置选项取消特定的自动收集遥测：

{
  "instrumentation": {
    "azureSdk": {
      "enabled": false
    },
    "cassandra": {
      "enabled": false
    },
    "jdbc": {
      "enabled": false
    },
    "jms": {
      "enabled": false
    },
    "kafka": {
      "enabled": false
    },
    "micrometer": {
      "enabled": false
    },
    "mongo": {
      "enabled": false
    },
    "quartz": {
      "enabled": false
    },
    "rabbitmq": {
      "enabled": false
    },
    "redis": {
      "enabled": false
    },
    "springScheduling": {
      "enabled": false
    }
  }
}

还可将以下环境变量设置为 false，以取消这些检测：

• APPLICATIONINSIGHTS_INSTRUMENTATION_AZURE_SDK_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_CASSANDRA_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_JDBC_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_JMS_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_KAFKA_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_MICROMETER_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_MONGO_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_RABBITMQ_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_REDIS_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_SPRING_SCHEDULING_ENABLED

然后，这些变量优先于 JSON 配置中指定的已启用变量。

注意

如果要查找更精细的控件，例如，要取消某些 redis 调用，而不是所有 redis 调用，请参阅采样替代。

预览版检测

从版本 3.2.0 开始，可以启用以下预览版检测：

{
  "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
      }
    }
  }
}

注意

从版本 3.2.2 开始可以使用 Akka 检测。 从版本 3.3.0 开始可以使用 Vertx HTTP 库检测。

指标间隔

默认情况下，每 60 秒捕获一次指标。

从 3.0.3 版本开始，可以更改此间隔：

{
  "metricIntervalSeconds": 300
}

从 3.4.9 GA 开始，还可使用环境变量 APPLICATIONINSIGHTS_METRIC_INTERVAL_SECONDS 设置 metricIntervalSeconds。 它优先于 JSON 配置中指定的 metricIntervalSeconds。

该设置适用于以下指标：

• 默认性能计数器：例如 CPU 和内存
• 默认自定义指标：例如垃圾回收计时
• 配置的 JMX 指标：参阅 JMX 指标部分
• Micrometer 指标：参阅自动收集的 Micrometer 指标部分

检测信号

默认情况下，Application Insights Java 3.X 每 15 分钟发送一个检测信号指标。 如果使用检测信号指标来触发警报，则可增加此检测信号的频率：

{
  "heartbeat": {
    "intervalSeconds": 60
  }
}

注意

不可将间隔增加到超过 15 分钟，因为检测信号数据也用于跟踪 Application Insights 使用情况。

身份验证

注意

身份验证功能从版本 3.4.17 开始正式发布。

可以使用身份验证配置代理以生成 Microsoft Entra 身份验证所需的令牌凭据。 有关详细信息，请参阅身份验证文档。

HTTP 代理

如果应用程序位于防火墙后面，并且无法直接连接到 Application Insights，请参阅 Application Insights 使用的 IP 地址。

若要解决此问题，可以将 Application Insights Java 3.x 配置为使用 HTTP 代理。

{
  "proxy": {
    "host": "myproxy",
    "port": 8080
  }
}

还可以使用环境变量 APPLICATIONINSIGHTS_PROXY 来设置 http 代理，该变量采用 https://<host>:<port> 格式。 它优先于 JSON 配置中指定的代理。

Application Insights Java 3.x 还沿用全局 https.proxyHost 和 https.proxyPort 系统属性，前提是这些属性已经设置完成（如有需要还沿用 http.nonProxyHosts）。

从引入失败中恢复

将遥测数据发送到 Application Insights 服务失败时，Application Insights Java 3.x 会将遥测存储到磁盘并继续从磁盘重试。

磁盘暂留的默认限制为 50 Mb。 如果遥测量较高，或者需要能够从较久的网络或引入服务中断中恢复，可以从版本 3.3.0 开始增加此限制：

{
  "preview": {
    "diskPersistenceMaxSizeMb": 50
  }
}

自我诊断

“自我诊断”指的是 Application Insights Java 3.X 的内部日志记录。 此功能可用于发现和诊断 Application Insights 本身的问题。

默认情况下，Application Insights Java 3.X 将对照以下配置，在 INFO 级别将日志记录到文件 applicationinsights.log 和控制台：

{
  "selfDiagnostics": {
    "destination": "file+console",
    "level": "INFO",
    "file": {
      "path": "applicationinsights.log",
      "maxSizeMb": 5,
      "maxHistory": 1
    }
  }
}

在前面的配置示例中：

• level 可以为 OFF、ERROR、WARN、INFO、DEBUG 或 TRACE 中的一个。
• path 可以是绝对或相对路径。 相对路径根据 applicationinsights-agent-3.5.1.jar 所在的目录进行解析。

从版本 3.0.2 开始，还可以使用环境变量 APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL 设置自我诊断 level。 它优先于 JSON 配置中指定的自我诊断级别。

从版本 3.0.3 开始，还可以使用环境变量 APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_FILE_PATH 设置自我诊断文件位置。 它优先于 JSON 配置中指定的自我诊断文件路径。

示例

此示例显示了包含多个组件的配置文件的外观。 请根据需要配置特定选项。

{
  "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
    }
  }
}