为 Java 配置 Azure Monitor Application Insights

本文介绍如何为 Java 配置 Azure Monitor Application Insights。 有关详细信息，请参阅 OpenTelemetry 入门。

配置Java代理

JSON 配置源

自定义维度

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

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

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

继承的属性（预览版）

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

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

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

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

另请参阅 向 Span 添加自定义属性。

配置采样替代

采样超控允许覆盖默认采样百分比。 例如，你能够：

• 将采样百分比设置为 0 或某个较小的值，以应对嘈杂的健康检查。
• 将采样百分比设置为 0 或较小的值，以应对依赖项调用中的噪声问题。
• 将重要请求类型的采样百分比设置为 100。 例如，即使已将默认采样配置为较低的值，也可以使用 /login。

采样优先于术语

在了解采样替代之前，应了解术语“范围”。

跨度是一种用于表示以下内容的遥测类型：

• 传入的请求。
• 传出的依赖项（例如，对另一个服务的远程调用）。
• 进程内依赖项（例如，由服务的子组件所做的工作）。

对于采样替代而言，这些范围组件非常重要：

• 特性

范围属性表示给定请求或依赖项的标准属性和自定义属性。

采样重写入门

首先，创建一个名为“applicationinsights.json”的配置文件。 将其保存在与“applicationinsights-agent-*.jar”相同的目录中。 请使用以下模版。

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10,
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 0
      },
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 100
      }
    ]
  }
}

采样替代的工作原理

telemetryType (Application Insights 3.4.0 中的 telemetryKind) 必须是 request、dependency、trace (日志) 或 exception。

当开始一个范围时，会使用该范围的类型以及当时存在于其上的属性来检查是否有任何匹配的采样替代。 匹配项可为 strict 或 regexp。 正则表达式匹配是针对整个属性值执行的，因此如果要匹配其中任何位置包含 abc 的值，则需要使用 .*abc.*。

采样替代可以指定多个属性条件，在这种情况下，所有属性条件都必须匹配，才能使采样替代匹配。 如果有一个采样替代匹配，则使用其采样百分比来确定是否要对该范围采样。

只使用匹配的第一个采样替代。 如果没有采样替代匹配：

• 如果是在跟踪中的第一个跨度，则使用顶层采样配置。
• 如果不是跟踪中的第一个范围，则会使用父采样决策。

可用于采样的范围属性

OpenTelemetry 范围属性为自动收集，且基于 OpenTelemetry 语义约定。

你还能以编程方式添加范围属性，并将其用于采样。

采样覆盖用例

展开以下任何用例以查看示例配置。

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
        {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/health-check",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "db.system",
            "value": "redis",
            "matchType": "strict"
          },
          {
            "key": "db.statement",
            "value": "GET my-noisy-key",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10
  },
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/login",
            "matchType": "strict"
          }
        ],
        "percentage": 100
      }
    ]
  }
}

dependencies
| where timestamp > ago(30d)
| where name == 'SQL: DB Query'
| summarize count() by name, operation_Name, data
| sort by count_ desc

SQL: DB Query    POST /Order             DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    36712549
SQL: DB Query    POST /Receipt           DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    2220248
SQL: DB Query    POST /CheckOutForm      DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    554074
SQL: DB Query    GET /ClientInfo         DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    37064

{
  "attributes": {
    "data": {
      "thread.name": "DefaultDatabaseBroadcastTransport: MessageReader thread",
      "thread.id": 96,
      "db.connection_string": "apache:",
      "db.statement": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
      "db.system": "other_sql",
      "applicationinsights.internal.item_count": 1
    }s
  }
}

{
  "connectionString": "...",
  "preview": {
    "sampling": {
      "overrides": [
        {
          "telemetryType": "dependency",
          "attributes": [
            {
              "key": "db.statement",
              "value": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
              "matchType": "strict"
            }
          ],
          "percentage": 0
        }
      ]
    }
  }
}

dependencies
| where timestamp > ago(30d)
| where data contains 'DECLARE @MyVar'
| summarize max(timestamp) by data
| sort by max_timestamp desc

DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    11/13/2023 8:52:41 PM 

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MdcClass {

  private static final Logger logger = LoggerFactory.getLogger(MdcClass.class);

  void method() {
    MDC.put("key", "value");
    try {
      logger.info(...); // Application log to remove
    } finally {
      MDC.remove("key"); // In a finally block in case an exception happens with logger.info
    }
  }
}

{
  "sampling": {
    "overrides": [
      {
        "telemetryType": "trace",
        "percentage": 0,
        "attributes": [
          {
            "key": "key",
            "value": "value",
            "matchType": "strict"
          }
        ]
      }
    ]
  }
}

<dependency>
  <groupId>io.opentelemetry.instrumentation</groupId>
  <artifactId>opentelemetry-instrumentation-annotations</artifactId>
</dependency>

package org.springframework.samples.petclinic.vet;

@Controller
class VetController {

  private final VetRepository vetRepository;

  public VetController(VetRepository vetRepository) {
    this.vetRepository = vetRepository;
  }

  @GetMapping("/vets.html")
  public String showVetList(@RequestParam(defaultValue = "1") int page, Model model) {
    Vets vets = new Vets();
    Page<Vet> paginated = findPaginated(page);
    vets.getVetList().addAll(paginated.toList());
    return addPaginationModel(page, paginated, model);
  }

  @WithSpan
  private Page<Vet> findPaginated(int page) {
    int pageSize = 5;
    Pageable pageable = PageRequest.of(page - 1, pageSize);
    return vetRepository.findAll(pageable); // Execution of SQL requests
  }
}

"sampling": {
  "overrides": [
    {
      "telemetryType": "dependency",
      "attributes": [
        {
          "key": "code.function",
          "value": "findPaginated",
          "matchType": "strict"
        }
      ],
      "percentage": 0
    }
  ]
}

"sampling": {
  "overrides": [
    {
      "telemetryType": "dependency",
      "attributes": [
        {
          "key": "code.namespace",
          "value": "org.springframework.samples.petclinic.vet.VetController",
          "matchType": "strict"
        }
      ],
      "percentage": 0
    }
  ]
}

采样替代故障排除

请参阅专用疑难解答文章。

采样替代常见问题解答

若要查看常见问题解答，请参阅 采样替代FAQ。

配置遥测数据的收集

本节内容：

• 配置 JMX 指标
• 自动收集日志记录
• 自动收集的微计指标（包括 Spring Boot 执行器指标）
• Autocollect InProc 依赖项（预览版）
• 浏览器 SDK 加载程序（预览版）

配置 JMX 指标

如何收集额外的 JMX 指标

默认情况下，Application Insights Java 3.x 收集一些Java管理扩展（JMX）指标，但在许多情况下，它是不够的。 本部分详细介绍了 JMX 配置选项。

可以通过向 "jmxMetrics"applicationinsights.json 文件中添加一个 "jmxMetrics" 节来配置 JMX 指标收集。 输入要在 Azure 门户的 Application Insights 资源中显示的指标名称。 要收集的每个指标都需要对象名称和特性。 可以在 * 对象名称中使用 glob 样式通配符。

如何了解可用于配置的指标

各种库、框架和应用程序服务器的属性（如对象名称和属性）不同，通常记录不充分。

若要查看特定环境的可用 JMX 指标，请将自诊断级别设置为 DEBUG 配置文件中 applicationinsights.json ，例如：

{
  "selfDiagnostics": {
    "level": "DEBUG"
  }
}

具有对象名称和属性名称的可用 JMX 指标会显示在 Application Insights 日志文件中。

日志文件输出的外观类似于这些示例。 在某些情况下，它可能非常广泛。

还可以使用 命令行工具检查可用的 JMX 指标。

JMX 配置示例

了解哪些指标可用后，可以配置代理以收集这些指标。

"jmxMetrics": [
  {
    "name": "Demo - GC Thread Count",
    "objectName": "java.lang:type=GarbageCollector,name=PS MarkSweep",
    "attribute": "LastGcInfo.GcThreadCount"
  },
  {
    "name": "Demo - GC Collection Count",
    "objectName": "java.lang:type=GarbageCollector,name=PS MarkSweep",
    "attribute": "CollectionCount"
  },
  {
    "name": "Demo - Thread Count",
    "objectName": "java.lang:type=Threading",
    "attribute": "ThreadCount"
  }
]

"jmxMetrics": [
  {
    "name": "Demo - G1 Collection Count Young",
    "objectName": "java.lang:name=G1 Young Generation,type=GarbageCollector",
    "attribute": "CollectionCount"
  },
  {
    "name": "Demo - G1 Collection Count Old",
    "objectName": "java.lang:name=G1 Old Generation,type=GarbageCollector",
    "attribute": "CollectionCount"
  },
  {
    "name": "Demo - Thread Count",
    "objectName": "java.lang:type=Threading",
    "attribute": "ThreadCount"
  }
]

如果要收集其他一些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 度量值。 布尔 JMX 指标将 false 映射到 0，将 true 映射到 1。

在 Application Insights 中查找 JMX 指标的位置

可以通过导航到 Azure 门户中的 Application Insights 资源，查看应用程序运行时收集的 JMX 指标。 在“ 指标 ”窗格中，选择下拉列表，如下所示以查看指标。

自动收集日志记录

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

日志记录仅在以下条件下被捕获：

• 满足日志框架的配置级别。
• 同时符合 Application Insights 的配置级别。

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

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

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

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

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

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

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

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

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

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

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

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

如果应用程序使用 Spring Boot 执行器，则 Spring Boot 执行器配置的指标也会自动收集。

使用 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
    }
  }
}

Autocollect InProc 依赖项（预览版）

如果要捕获控制器“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
    }
  }
}

配置遥测处理器（预览版）

可以使用遥测处理器配置应用于请求、依赖项和跟踪遥测的规则。 Application Insights Java 3.x 可以在导出数据之前处理遥测数据。

用例：

• 屏蔽敏感数据。
• 有条件地添加自定义维度。
• 更新范围名称，该名称用于在Azure门户中聚合类似的遥测数据。
• 删除特定的跨度属性以控制数据处理成本。
• 筛选出一些指标来控制引入成本。

如果您希望丢弃特定的完整范围以控制摄取成本，请参阅配置采样替代。

遥测处理器术语

在了解遥测处理器之前，应了解术语 范围 和 日志。

跨度是一种用于表示以下内容的遥测类型：

• 传入的请求。
• 传出的依赖项（例如，对另一个服务的远程调用）。
• 进程内依赖项（例如，由服务的子组件所做的工作）。

日志是表示的遥测类型：

• 从 Log4j、Logback 和 java.util.logging 捕获的日志数据

对于遥测处理器，以下跨度/日志组件非常重要：

遥测处理器的类型

目前，四种类型的遥测处理器包括：

遥测处理器入门

首先，创建一个名为“applicationinsights.json”的配置文件。 将其保存在与“applicationinsights-agent-*.jar”相同的目录中。 请使用以下模版。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
] 

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
] 

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

遥测处理器示例

"processors": [
  {
    "type": "attribute",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "redact_trace",
          "value": "false"
        }
      ]
    },
    "actions": [
      {
        "key": "credit_card",
        "action": "delete"
      },
      {
        "key": "duplicate_key",
        "action": "delete"
      }
    ]
  }
]

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "attribute1",
            "value": "attributeValue1",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "newKey",
            "fromAttribute": "anotherKey",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "db.secret",
            "value": "redacted",
            "action": "update"
          },
          {
            "key": "boo",
            "fromAttribute": "foo",
            "action": "update" 
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "user.email",
            "action": "hash"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
            "action": "extract"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "user\\/\\d+",
            "replace": "user\\/****",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
            "replace": "${userGroupName}**",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "longAttributeKey",
              "value": 1234,
              "type": "long"
            },
            {
              "key": "booleanAttributeKey",
              "value": true,
              "type": "boolean"
            },
            {
              "key": "doubleArrayAttributeKey",
              "value": [1.0, 2.0, 3.0, 4.0],
              "type": "double-array"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyStrict",
            "value": "newAttributeValueStrict",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyStrict"
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "regexp",
          "attributes": [
            {
              "key": "longRegexpAttributeKey",
              "value": "4[0-9][0-9]",
              "type": "long"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyRegexp",
            "value": "newAttributeValueRegexp",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyRegexp"
      }
    ]
  }
}

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "fromAttributes": [
            "db.svc",
            "operation",
            "id"
          ],
          "separator": "::"
        }
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "toAttributes": {
            "rules": [
              "^/api/v1/document/(?<documentId>.*)/update$"
            ]
          }
        }
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "regexp",
          "spanNames": [
            "^(.*?)/(.*?)$"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "donot/change"
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [
              "(?<operation_website>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
            ]
          }
        }
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "userId (?<redactedUserId>[0-9a-zA-Z]+)"
            ]
          }
        }
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "redactedUserId",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

包括和排除范围示例

展开以下部分以查看各种包含和排除范围示例。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ],
          "attributes": [
            {
              "key": "env",
              "value": "dev"
            },
            {
              "key": "test_request"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "redact_trace",
              "value": "false"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          },
          {
            "key": "duplicate_key",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

遥测处理器常见问题解答

若要查看常见问题解答（常见问题解答），请参阅 遥测处理器常见问题解答

替代或禁止默认行为

本节内容：

• 连接字符串替代（预览版）
• 云角色名称重写（预览版）
• 在运行时配置连接字符串
• 本地禁用摄取采样（预览版）

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

此功能为预览版，从 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"
      }
    ]
  }
}

在运行时配置连接字符串

如果需要在运行时配置连接字符串，请将此属性添加到 JSON 配置中：

{
  "connectionStringConfiguredAtRuntime": true
}

向应用程序添加 applicationinsights-core：

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

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

本地禁用摄取采样（预览版）

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

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

从 3.5.3 开始，您可以禁用此行为：这样，在这些情况下，即使在您的 Application Insights 资源上配置了数据采集抽样，依然可以保持 100% 的遥测。

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

保护遥测数据

查询掩码

默认情况下，Java数据库连接（JDBC）和 Mongo 查询中的文本值将被屏蔽，以避免意外捕获敏感数据。

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

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

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

HTTP 标头

可以在服务器（请求）和客户端（依赖项）遥测上捕获请求和响应标头：

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

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

配置运行时和环境配置

本节内容：

• 身份验证
• HTTP 代理
• 指标间隔
• 心跳
• 从引入失败中恢复
• 自我诊断
• 遥测关联

身份验证

可以使用身份验证将代理配置为生成Microsoft Entra身份验证所需的 token 凭据。

HTTP 代理

如果应用程序位于防火墙后面且无法直接连接到 Application Insights，请参阅 Azure Monitor 终结点访问和防火墙配置。

若要解决此问题，可以将 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。

度量间隔

默认情况下，每 60 秒捕获一次指标。 可以更改此间隔：

{
  "metricIntervalSeconds": 300
}

从 Java 代理版本 3.4.9（GA）开始，还可以使用环境变量 metricIntervalSeconds设置 APPLICATIONINSIGHTS_METRIC_INTERVAL_SECONDS。 它优先于 JSON 配置中指定的 metricIntervalSeconds。

该设置适用于以下指标：

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

心跳信号

默认情况下，Application Insights Java 3.x 每隔 15 分钟发送一次心跳指标。 如果您使用心跳指标来触发警报，可以增加心跳的频率：

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

从引入失败中恢复

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

磁盘暂留的默认限制为 50 Mb。 如果遥测数据量较高，或者需要能够从较长时间的网络或数据接收服务中断中恢复，那么可以提高此限制。

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

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

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

遥测关联

默认情况下启用遥测关联，但你可以在配置中禁用它：

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

高级和预览功能

自定义检测（预览版）

可以在应用程序中捕获方法的跨度：

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

预览仪器

可以启用以下预览工具：

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

配置文件示例

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

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