从 Application Insights Java 2.x SDK 升级Upgrading from Application Insights Java 2.x SDK

如果已在应用程序中使用 Application Insights Java 2.x SDK,则无需将其删除。If you're already using Application Insights Java 2.x SDK in your application, there is no need to remove it. Java 3.0 代理会检测到它,并捕获和关联你通过 2.x SDK 发送的任何自定义遥测,同时禁止 2.x SDK 执行的任何自动收集以防止重复遥测。The Java 3.0 agent will detect it, and capture and correlate any custom telemetry you're sending via the 2.x SDK, while suppressing any auto-collection performed by the 2.x SDK to prevent duplicate telemetry.

如果你使用的是 Application Insights 2.x 代理,则需要删除指向 2.x 代理的 -javaagent: JVM 参数。If you were using Application Insights 2.x agent, you need to remove the -javaagent: JVM arg that was pointing to the 2.x agent.

本文档的其余部分介绍了从 2.x 升级到 3.0 时可能遇到的限制和更改,以及你可能认为有帮助的一些解决方法。The rest of this document describes limitations and changes that you may encounter when upgrading from 2.x to 3.0, as well as some workarounds that you may find helpful.

TelemetryInitializers 和 TelemetryProcessorsTelemetryInitializers and TelemetryProcessors

使用 3.0 代理时,2.x SDK TelemetryInitializer 和 TelemetryProcessor 不会运行。The 2.x SDK TelemetryInitializers and TelemetryProcessors will not be run when using the 3.0 agent. 许多以前需要这些项的用例可以在 3.0 中通过配置自定义维度或配置遥测处理器来解决。Many of the use cases that previously required these can be solved in 3.0 by configuring custom dimensions or configuring telemetry processors.

单个 JVM 中的多个应用程序Multiple applications in a single JVM

目前,3.0 仅支持一个正在运行的进程使用一个连接字符串和角色名称Currently, 3.0 only supports a single connection string and role name per running process. 特别是,你不能使用不同的连接字符串或不同的角色名称在相同的 tomcat 部署中拥有多个 tomcat Web 应用。In particular, you can't have multiple tomcat web apps in the same tomcat deployment using different connection strings or different role names yet.

操作名称Operation names

3.0 中的操作名称已更改,通常在 Application Insights 门户 U/X 中提供更好的聚合视图。Operation names in 3.0 have changed to generally provide a better aggregated view in the Application Insights Portal U/X.

3.0 中的操作名称

但是,对于某些应用程序,你可能仍然更喜欢由以前的操作名称提供的 U/X 中的聚合视图;这样的话,你可使用 3.0 中的遥测处理器(预览版)功能来复制以前的行为。However, for some applications, you may still prefer the aggregated view in the U/X that was provided by the previous operation names, in which case you can use the telemetry processors (preview) feature in 3.0 to replicate the previous behavior.

使用 http 方法(GETPOST 等)为操作名称添加前缀Prefix the operation name with the http method (GET, POST, etc.)

在 2.x SDK 中,操作名称由 http 方法(GETPOST 等)添加前缀,例如In the 2.x SDK, the operation names were prefixed by the http method (GET, POST, etc.), e.g

由 http 方法添加前缀的操作名称

从 3.0.3 开始,你可使用以下项返回此 2.x 版行为Starting in 3.0.3, you can bring back this 2.x behavior using

{
  "preview": {
    "httpMethodInOperationName": true
  }
}

将操作名称设置为完整路径Set the operation name to the full path

此外在 2.x SDK 中,某些情况下操作名称包含完整路径,例如Also, in the 2.x SDK, in some cases, the operation names contained the full path, e.g.

带有完整路径的操作名称

下面的片段配置了 4 个遥测处理器,它们组合在一起来复制以前的行为。The snippet below configures 4 telemetry processors that combine to replicate the previous behavior. 遥测处理器会(按顺序)执行以下操作:The telemetry processors perform the following actions (in order):

  1. 第一个遥测处理器是范围处理器(具有类型 span),这意味着它适用于 requestsdependenciesThe first telemetry processor is a span processor (has type span), which means it applies to requests and dependencies.

    它将匹配具有 http.url 属性的任何范围。It will match any span that has an attribute named http.url.

    然后,它将更新包含 http.url 属性值的范围名称。Then it will update the span name with the http.url attribute value.

    这将是它的末尾部分,只是 http.url 看起来像 http://host:port/path,而你可能只想要 /path 部分。This would be the end of it, except that http.url looks something like http://host:port/path, and it's likely that you only want the /path part.

  2. 第二个遥测处理器也是范围处理器。The second telemetry processor is also a span processor.

    它将匹配具有 http.url 属性的任何范围(也就是第一个处理器匹配的任何范围)。It will match any span that has an attribute named http.url (in other words, any span that the first processor matched).

    然后,它将范围名称的路径部分提取到名为 tempName 的属性中。Then it will extract the path portion of the span name into an attribute named tempName.

  3. 第三个遥测处理器也是范围处理器。The third telemetry processor is also a span processor.

    它将匹配具有 tempPath 属性的任何范围。It will match any span that has an attribute named tempPath.

    然后,它将更新属性 tempPath 中的范围名称。Then it will update the span name from the attribute tempPath.

  4. 最后一个遥测处理器是属性处理器(具有类型 attribute),这意味着它适用于所有具有属性(当前是 requestsdependenciestraces)的遥测。The last telemetry processor is an attribute processor (has type attribute), which means it applies to all telemetry which has attributes (currently requests, dependencies and traces).

    它将匹配具有 tempPath 属性的任何遥测。It will match any telemetry that has an attribute named tempPath.

    然后,它将删除名为 tempPath 的属性,使其不被报告为自定义维度。Then it will delete the attribute named tempPath, so that it won't be reported as a custom dimension.

{
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.url" }
          ]
        },
        "name": {
          "fromAttributes": [ "http.url" ]
        }
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "http.url" }
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [ "https?://[^/]+(?<tempPath>/[^?]*)" ]
          }
        }
      },
      {
        "type": "span",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "name": {
          "fromAttributes": [ "tempPath" ]
        }
      },
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            { "key": "tempPath" }
          ]
        },
        "actions": [
          { "key": "tempPath", "action": "delete" }
        ]
      }
    ]
  }
}

依赖项名称Dependency names

3.0 中的依赖项名称也已更改,同样通常在 Application Insights 门户 U/X 中提供更好的聚合视图。Dependency names in 3.0 have also changed, again to generally provide a better aggregated view in the Application Insights Portal U/X.

同样地,对于某些应用程序,你可能仍然更喜欢由以前的依赖项名称提供的 U/X 中的聚合视图;这样的话,你可使用与上述类似技术来复制以前的行为。Again, for some applications, you may still prefer the aggregated view in the U/X that was provided by the previous dependency names, in which case you can use similar techniques as above to replicate the previous behavior.

依赖项的操作名称Operation name on dependencies

以前在 2.x SDK 中,请求遥测中的操作名称也设置在依赖项遥测上。Previously in the 2.x SDK, the operation name from the request telemetry was also set on the dependency telemetry. Application Insights Java 3.0 不再在依赖项遥测上填充操作名称。Application Insights Java 3.0 no longer populates operation name on dependency telemetry. 如果要查看作为依赖项遥测父级的请求的操作名称,可编写日志 (Kusto) 查询以从依赖项表联接到请求表,例如If you want to see the operation name for the request that is the parent of the dependency telemetry, you can write a Logs (Kusto) query to join from the dependency table to the request table, e.g.

let start = datetime('...');
let end = datetime('...');
dependencies
| where timestamp between (start .. end)
| project timestamp, type, name, operation_Id
| join (requests
    | where timestamp between (start .. end)
    | project operation_Name, operation_Id)
    on $left.operation_Id == $right.operation_Id
| summarize count() by operation_Name, type, name

2.x SDK 日志记录追加器2.x SDK logging appenders

3.0 代理自动收集日志记录,无需配置任何日志记录追加器。The 3.0 agent auto-collects logging without the need for configuring any logging appenders. 如果使用的是 2.x SDK 日志记录追加器,则可以将其删除,因为它们仍会被 3.0 代理禁止。If you are using 2.x SDK logging appenders, those can be removed, as they will be suppressed by the 3.0 agent anyways.

2.x SDK Spring Boot 入门版2.x SDK spring boot starter

没有 3.0 Spring Boot 入门版。There is no 3.0 spring boot starter. 无论是否使用的是 Spring Boot,3.0 代理的设置和配置都遵循相同的简单步骤The 3.0 agent setup and configuration follows the same simple steps whether you are using spring boot or not.

请注意,从 2.x SDK Spring Boot 入门版升级时,云角色名称将不再默认为 spring.application.nameWhen upgrading from the 2.x SDK spring boot starter, note that the cloud role name will no longer default to spring.application.name. 若要了解如何通过 json 配置或环境变量在 3.0 中设置云角色名称,请参阅 3.0 配置文档See the 3.0 configuration docs for setting the cloud role name in 3.0 via json config or environment variable.