前端/UI 配置

配置

UI 的多个方面可以进行配置：

• 可以启用主题功能以支持在浅色和深色模式之间切换
• 可以启用/配置依赖关系部分
• 可以启用/配置监控选项卡（又称：服务性能监控）
• 可以启用/配置应用分析追踪（通过 Google Analytics 或自定义插件）
• 可以向全局导航栏添加额外的菜单选项
• 可以配置搜索输入限制
• 可以启用关键路径可视化
• 可以配置标签显示优先级
• 可以针对嵌入场景禁用各种 UI 控件

这些选项可以通过一个 JSON 配置文件传递给查询扩展来进行配置：

extensions:
  jaeger_query:
    ui:
      config_file: /path/to/config-ui.json

配置文件示例（参见完整模式定义）：

{
  "dependencies": {
    "dagMaxNumServices": 200,
    "menuEnabled": true
  },
  "monitor": {
    "menuEnabled": true
  },
  "themes": {
    "enabled": true
  },
  "archiveEnabled": true,
  "tracking": {
    "gaID": "UA-000000-2",
    "trackErrors": true
  },
  "menu": [
    {
      "label": "About Jaeger",
      "items": [
        {
          "label": "GitHub",
          "url": "https://github.com/jaegertracing/jaeger"
        },
        {
          "label": "Docs",
          "url": "https://www.jaegertracing.io/docs/latest/"
        }
      ]
    }
  ],
  "search": {
    "maxLookback": {
      "label": "2 Days",
      "value": "2d"
    },
    "maxLimit": 1500
  },
  "linkPatterns": [{
    "type": "process",
    "key": "jaeger.version",
    "url": "https://github.com/jaegertracing/jaeger-client-java/releases/tag/#{jaeger.version}",
    "text": "Information about Jaeger release #{jaeger.version}"
  },
  {
    "type": "tags",
    "key": "uniqueId",
    "url": "https://mykibana.com/uniqueId=#{uniqueId}&traceId=#{trace.traceID}",
    "text": "Redirect to kibana to view log"
  },
  {
    "type": "traces",
    "url": "https://my-logs.server?from=#{startTime | add -60000000 | epoch_micros_to_date_iso}&to=#{endTime | add 60000000 | epoch_micros_to_date_iso}'",
    "text": "Redirect to kibana to view log with formatted dates"
  }],
  "traceIdDisplayLength": 20,
  "criticalPathEnabled": true,
  "topTagPrefixes": ["http.", "db."]
}

主题（浅色/深色模式）

用户可以使用顶部导航栏中的按钮在浅色和深色主题之间切换。选择的主题会持久化存储在浏览器的本地存储中。如果没有存储的主题，UI 将遵循用户的系统偏好设置（prefers-color-scheme）。

{
  "themes": {
    "enabled": true
  }
}

themes.enabled 启用（true）或禁用（false）主题切换按钮。默认值：false。如果主题切换被禁用，UI 将始终使用浅色主题。

依赖关系

dependencies.dagMaxNumServices 定义了在 DAG 依赖视图被禁用之前允许的最大服务数量。默认值：200。

dependencies.menuEnabled 启用（true）或禁用（false）依赖关系菜单按钮。默认值：true。

监控

monitor.menuEnabled 启用（true）或禁用（false）监控菜单按钮。默认值：false。

monitor.docsLink 指定服务性能监控相关文档的 URL。设置后，监控选项卡中会显示一个帮助链接。

monitor.emptyState 允许自定义在没有可用监控数据时的空状态显示：

{
  "monitor": {
    "menuEnabled": true,
    "docsLink": "https://www.jaegertracing.io/docs/latest/spm/",
    "emptyState": {
      "mainTitle": "Get started with Service Performance Monitoring",
      "subTitle": "No data available",
      "description": "Configure your services to emit RED metrics.",
      "info": "Additional information text",
      "alert": {
        "message": "SPM requires metrics storage backend",
        "type": "info"
      }
    }
  }
}

归档支持

archiveEnabled 启用（true）或禁用（false）归档链路追踪按钮。默认值：false。它需要在查询服务中配置归档存储。归档的链路追踪只能通过 ID 直接访问，不可搜索。

应用分析追踪

tracking.gaID 定义 Google Analytics 跟踪 ID。这是 Google Analytics 跟踪所必需的，将其设置为非 null 值即可启用 Google Analytics 跟踪。默认值：null。

tracking.customWebAnalytics 定义自定义跟踪插件的工厂函数（仅在使用 JavaScript 形式的 UI 配置时适用）。

tracking.trackErrors 启用（true）或禁用（false）错误跟踪。只有在配置了有效的分析跟踪器时才能跟踪错误。默认值：true。

有关应用分析的更多详细信息，请参阅 UI 仓库中的跟踪 README。

自定义菜单项

menu 允许向全局导航栏添加额外的链接。这些额外的链接会右对齐。

在上面的 JSON 配置示例中，配置的菜单将有一个标签为 "About Jaeger" 的下拉菜单，其中包含 "GitHub" 和 "Docs" 子选项。顶部右侧菜单中链接的格式如下：

{
  "label": "Some text here",
  "url": "https://example.com"
}

链接可以直接作为 menu 数组的成员，也可以分组到一个下拉菜单选项中。链接分组的格式如下：

{
  "label": "Dropdown button",
  "items": [ ]
}

items 数组应包含一个或多个链接配置。

搜索输入限制

search.maxLimit 配置搜索输入允许的最大结果数。

search.maxLookback 配置用户可以查询链路追踪的最大回溯时间。回溯下拉菜单中大于此值的选项将不会显示。

字段	描述
label	在搜索表单下拉菜单中显示的文本
value	选择该标签时在搜索查询中提交的值

链接模式

linkPatterns 节点可用于从 Jaeger UI 中显示的字段创建链接。

字段	描述
type	链接将被添加到的元数据部分：process、tags、logs、traces
key	标签/进程/日志属性的名称，其值将显示为链接，对于 traces 类型此字段不是必需的。
url	链接应指向的 URL，可以是外部站点或 Jaeger UI 中的相对路径
text	链接的工具提示中显示的文本

url 和 text 都可以定义为模板（即使用 #{field-name}），Jaeger UI 将根据 tags/logs/traces 数据动态替换值。

对于 traces，支持的模板字段有：duration、endTime、startTime、traceName 和 traceID。

此外，当链路追踪模板字段以 trace. 为前缀时，它们也可以在 process/logs/tags 类型中用于替换。例如：trace.traceID、trace.startTime。

格式化

除了将字段插值到链接中外，还可以使用格式化函数。语法为 #{field | function}（例如 #{endTime | epoch_micros_to_date_iso}'）。格式化函数可以链式调用（例如 #{startTime | add 60000000 | epoch_micros_to_date_iso}）。

可用的格式化函数及其行为描述如下：

`epoch_micros_to_date_iso`

将微秒级 epoch 时间戳格式化为 ISO 日期时间。

示例：
#{endTime | epoch_micros_to_date_iso}

`pad_start`

用给定字符填充字符串的开头，直到结果字符串达到给定长度。行为与 JavaScript 的 String.padStart 一致。

参数：

• targetLength（整数）- 填充后字符串的目标长度
• padCharacter（字符串）- 用于填充输入字符串开头的字符串

示例：#{traceID | pad_start 32 0}

`add`

向另一个数字添加一个值。可以是正数或负数。

参数：

• offset（整数）- 要添加到输入数字的值

示例：#{startTime | add 1000000}

Trace ID 显示长度

traceIdDisplayLength 设置控制 Jaeger UI 中显示的 trace ID 字符数（例如，在链路追踪列表或链路追踪详情头部中）。这对于提高可读性或与日志或仪表盘等其他系统中的 trace ID 对齐非常有用。

字段	描述
traceIdDisplayLength	可选。整数值，决定从 trace ID 显示的字符数。默认值为 7。

示例：

{
  "traceIdDisplayLength": 12
}

这将显示如 1a2b3c4d5e6f 的 trace ID（而不是完整的 32 字符 ID 或默认的 7 字符）。

关键路径

criticalPathEnabled 启用（true）或禁用（false）链路追踪视图中的关键路径可视化。启用后，每个 span 的关键路径将被高亮显示，展示哪些操作位于整体链路追踪持续时间的关键路径上。默认值：true。

{
  "criticalPathEnabled": true
}

顶部标签前缀

topTagPrefixes 定义一组 span 标签名称的前缀，这些前缀被视为"重要的"，匹配的标签将在 span 详情的标签列表中显示在更高的位置。例如，将 topTagPrefixes 设置为 ["http."] 将使所有以 "http." 开头的 span 标签显示在其他所有标签之上。

{
  "topTagPrefixes": ["http.", "db.", "rpc."]
}

链路追踪图

traceGraph.layoutManagerMemory 控制用于渲染链路追踪图的 GraphViz 模块实例的可用总内存。该值应为 2 的幂。默认的 16MB 对大多数情况应该足够——只有在遇到 "Cannot enlarge memory arrays" 错误时才考虑使用更大的值。

{
  "traceGraph": {
    "layoutManagerMemory": 33554432
  }
}

UI 控件

有几个选项可以禁用特定的 UI 控件，这对于嵌入场景或限制功能非常有用：

disableFileUploadControl 禁用（true）或启用（false）用于加载链路追踪 JSON 文件的文件上传控件。默认值：false。

disableJsonView 禁用（true）或启用（false）链路追踪视图中的 JSON 视图选项。默认值：false。

forbidNewPage 设置为 true 时，会修改所有链接目标以阻止打开新的浏览器标签页/窗口。当将 UI 嵌入到另一个应用程序中时这非常有用。默认值：false。

{
  "disableFileUploadControl": true,
  "disableJsonView": true,
  "forbidNewPage": true
}

嵌入模式

从 1.9 版本开始，Jaeger UI 提供了一种"嵌入"布局模式，旨在支持将 Jaeger UI 集成到其他应用程序中。目前（v0 阶段），采用的方法是从页面中移除各种 UI 元素，使 UI 更适合空间受限的布局。

嵌入模式通过 URL 查询参数来激活和配置。

要进入嵌入模式，必须在 URL 中添加 uiEmbed=v0 查询参数和值。例如，以下 URL 将以嵌入模式显示 ID 为 abc123 的链路追踪：

http://localhost:16686/trace/abc123?uiEmbed=v0

uiEmbed=v0 是必需的。

此外，对于每个支持的页面，会添加一个按钮 ，点击后将在新标签页中打开非嵌入页面。

以下页面支持嵌入模式：

• 搜索页面
• 链路追踪页面

搜索页面

要将搜索链路追踪页面集成到我们的应用程序中，我们需要通过 uiEmbed=v0 告知 Jaeger UI 使用嵌入模式。

例如：

http://localhost:16686/search?
    service=my-service&
    start=1543917759557000&
    end=1543921359557000&
    limit=20&
    lookback=1h&
    maxDuration&
    minDuration&
    uiEmbed=v0

配置选项

以下查询参数可用于配置搜索页面的布局：

• uiSearchHideGraph=1 - 禁用搜索结果上方散点图的显示

http://localhost:16686/search?
    service=my-service&
    start=1543917759557000&
    end=1543921359557000&
    limit=20&
    lookback=1h&
    maxDuration&
    minDuration&
    uiEmbed=v0&
    uiSearchHideGraph=1

链路追踪页面

要将链路追踪页面集成到我们的应用程序中，我们需要通过 uiEmbed=v0 告知 Jaeger UI 使用嵌入模式。

例如：

http://localhost:16686/trace/{trace-id}?uiEmbed=v0

如果我们从搜索链路追踪页面导航到此视图，将会有一个返回结果页面的按钮。

配置选项

以下查询参数可用于配置链路追踪页面的布局：

• uiTimelineCollapseTitle=1 使链路追踪头部以折叠状态启动，隐藏摘要和小地图。

http://localhost:16686/trace/{trace-id}?
    uiEmbed=v0&
    uiTimelineCollapseTitle=1

• uiTimelineHideMinimap=1 完全移除小地图，无论链路追踪头部是否展开。

http://localhost:16686/trace/{trace-id}?
    uiEmbed=v0&
    uiTimelineHideMinimap=1

• uiTimelineHideSummary=1 - 完全移除链路追踪摘要信息（服务数量等），无论链路追踪头部是否展开。

http://localhost:16686/trace/{trace-id}?
    uiEmbed=v0&
    uiTimelineHideSummary=1

我们还可以组合使用这些选项：

http://localhost:16686/trace/{trace-id}?
    uiEmbed=v0&
    uiTimelineHideMinimap=1&
    uiTimelineHideSummary=1