配置选项：适用于 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.6.0.jar 所在的目录中。

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

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

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

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

连接字符串

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

{
  "connectionString": "..."
}

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

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

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

如果你指定相对路径，系统会相对于 applicationinsights-agent-3.6.0.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 配置中指定的云角色实例。

采样

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

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

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

速率限制采样

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

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

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

以下示例演示如何将采样设置为每秒最多捕获（大约）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 配置中指定的采样百分比。

采样替代

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

• 将采样百分比设置为 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.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.6.0</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 门户中聚合类似遥测数据的范围名称。
• 删除范围属性以控制数据引入成本。

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

自定义检测（预览版）

从版本 3.3.1 开始，可以在应用程序中捕获方法的跨度：

{
  "preview": {
    "customInstrumentation": [
      {
        "className": "my.package.MyClass",
        "methodName": "myMethod"
      }
    ]
  }
}

在本地禁用引入采样（预览版）

默认情况下，如果 Java 代理中的有效采样百分比为 100%，并且已在 Application Insights 资源上配置引入采样，则将应用引入采样百分比。

请注意，此行为适用于 100% 的固定速率采样，在请求速率不超过速率限制情况下，还适用于速率限制采样（在持续滑动的时间窗口内，有效捕获率为 100%）。

从 3.5.3 开始，可以禁用此行为（并且在这些情况下保持 100% 的遥测，即使在 Application Insights 资源上配置了引入采样）：

{
  "preview": {
    "sampling": {
      "ingestionSamplingEnabled": false
    }
  }
}

自动收集的日志记录

将自动检测 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 值。 该表显示了它们如何对应于不同日志记录框架中的日志级别。

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 指标，请运行以下命令：

{
  "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
    },
    "logging": {
      "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_LOGGING_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_MICROMETER_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_MONGO_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_RABBITMQ_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_REDIS_ENABLED
• APPLICATIONINSIGHTS_INSTRUMENTATION_SPRING_SCHEDULING_ENABLED

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

预览版检测

从版本 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
      }
    }
  }
}

指标间隔

默认情况下，每 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
  }
}

HTTP 代理

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

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

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

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

可以使用 APPLICATIONINSIGHTS_PROXY 环境变量 https://<user>:<password>@<host>:<port> 为代理提供用户和密码。

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.6.0.jar 所在的目录进行解析。

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

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

遥测关联

遥测关联已默认启用，但你可以在配置中禁用它。

{
  "preview": {
    "disablePropagation": true
  }
}

示例

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

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