跳到主要内容

HOMER 集成

本文档涵盖了可选的 HOMER 集成，用于将应用程序日志与 SIP 跟踪相关联。

概述​

OmniTAS 可以通过 UDP 使用 HEP3（Homer 封装协议）将应用程序日志转发到 HOMER 服务器。使用 SIP Call-ID 将日志与 SIP 跟踪相关联，从而实现对呼叫处理和信令的端到端可见性。

工作原理​

  1. 日志元数据：在呼叫处理期间，OmniTAS 在记录器元数据中设置 SIP Call-ID
  2. 日志捕获：Homer 模块通过 PubSub 订阅日志消息
  3. 过滤：仅转发���含 call_id 元数据的日志
  4. HEP3 编码：日志被编码为 HEP3 数据包，协议类型为 100（日志）
  5. 关联：HOMER 使用 Call-ID 将日志与 SIP 跟踪相关联

配置​

将 homer_server 配置添加到您的 config/runtime.exs：

config :tas,
  homer_server: %{
    host: "10.179.2.136",
    port: 9060,
    auth_key: nil,
    capture_id: 2001
  }

参数​

参数类型必需默认描述
host字符串是-HOMER 服务器 IP 地址或主机名
port整数否9060HEP 接收器 UDP 端口
auth_key字符串否nil可选的 HEP 认证密钥。如果启用，请设置为与 heplify-server 配置中的 authkey 匹配
capture_id整数否2001捕获代理标识符。在 HOMER UI 中显示以识别日志源

禁用 HOMER 集成​

要禁用 HOMER 集成，可以：

  • 完全删除 homer_server 配置，或
  • 注释掉配置块

禁用后，Homer 模块不会启动，且不会转发任何日志。

HOMER 服务器要求​

HOMER 服务器必须运行 heplify-server，并启用 UDP 上的 HEP 接收。

heplify-server 配置​

验证您的 heplify-server.toml 包含：

HEPAddr = "0.0.0.0:9060"

支持的协议类型​

OmniTAS 发送协议类型为 100 的日志，heplify-server 将其路由到 logs_capture。确保您的 HOMER 数据库模式支持日志存储。

日志关联​

自动 Call-ID 注入​

OmniTAS 在以下情况下自动将 Call-ID 注入记录器元数据中：

  • MO 呼叫处理：处理移动发起的呼叫时
  • MT 呼叫处理：处理移动终止的呼叫时
  • 呼叫事件：处理接听和挂断事件时

日志格式​

发送到 HOMER 的日志包括：

字段描述
关联 ID用于跟踪关联的 SIP Call-ID
时间戳微秒精度的时间戳
级别日志级别（调试、信息、警告、错误）
消息日志消息内容
源 IPOmniTAS 服务器 IP 地址
捕获 ID配置的捕获代理标识符

HOMER 中的示例日志​

处理完呼叫后，HOMER 显示相关数据：

[info] 处理来自：61400123456 到：61400654321 的 MO 呼叫
[debug] 查找呼叫者：61400123456
[info] OCS 授权：已授予（120 秒）
[debug] 设置变量：hangup_case = none

这些日志与 HOMER 呼叫详细视图中的 SIP INVITE、200 OK 和 BYE 消息一起出现。

HEP3 协议细节​

OmniTAS 实现了 HOMER 项目定义的 HEP3，兼容 Kamailio 的 siptrace 模块。

使用的块类型​

块 ID名称描述
0x0001IP 家族始终为 2（IPv4）
0x0002IP 协议始终为 17（UDP）
0x0003源 IPv4OmniTAS 服务器地址
0x0004目标 IPv4HOMER 服务器地址
0x0007源端口0（日志不适用）
0x0008目标端口配置的 HEP 端口
0x0009时间戳秒Unix 时间戳秒
0x000A时间戳微秒微秒部分
0x000B协议类型100（日志）
0x000C捕获 ID配置的 capture_id
0x0011关联 IDSIP Call-ID
0x000F有效载荷日志消息
0x000E认证密钥可选认证

故障排除​

日志未出现在 HOMER 中​

症状：呼叫成功完成，但 HOMER 中没有日志出现

可能原因：

  • HOMER 服务器在配置的端口上不可达
  • 防火墙阻止 UDP 流量到端口 9060
  • heplify-server 未配置为接收 HEP
  • 日志缺少 call_id 元数据

解决方案：

  1. 验证网络连接：nc -zvu <homer_host> 9060
  2. 检查 heplify-server 是否在监听：ss -ulnp | grep 9060
  3. 查看 heplify-server 日志以获取传入数据包
  4. 验证 call_id 是否出现在 OmniTAS 日志中（检查日志输出中的 call_id=）

认证失败​

症状：heplify-server 日志显示认证错误

可能原因：

  • OmniTAS ��� heplify-server 之间的 auth_key 不匹配
  • 一方配置了认证密钥，但另一方未配置

解决方案：

  1. 如果 heplify-server 没有配置认证密钥，请在 OmniTAS 中设置 auth_key: nil
  2. 如果 heplify-server 需要认证，请在两个系统中配置匹配的密钥

缺失关联​

症状：日志出现在 HOMER 中，但未与 SIP 跟踪关联

可能原因：

  • SIP 和日志之间的 Call-ID 格式不匹配
  • HOMER 关联配置

解决方案：

  1. 验证日志中的 Call-ID 是否与 SIP Call-ID 头完全匹配
  2. 检查 HOMER 的关联设置是否适用于 logs_capture 表

指标​

启用 HOMER 集成时，监控以下指标：

OmniTAS 日志​

注意指示 HEP 传输失败的警告：

[warning] 无法将 HEP 数据包发送到 Homer：<reason>

heplify-server 指标​

如果在 heplify-server 上启用了 Prometheus 指标，请监控：

  • heplify_packets_total{type="log"} - 接收到的总日志数据包
  • heplify_packets_dropped_total - 丢弃的数据包（缓冲/解析错误）

架构参考​

组件交互​

数据流​

另见​