Skip to main content

HOMER Integration

This document covers the optional HOMER integration for correlating application logs with SIP traces.

Overview​

OmniTAS can forward application logs to a HOMER server using the HEP3 (Homer Encapsulation Protocol) over UDP. Logs are correlated with SIP traces using the SIP Call-ID, enabling end-to-end visibility of call processing alongside signaling.

How It Works​

  1. Log Metadata: During call processing, OmniTAS sets the SIP Call-ID in Logger metadata
  2. Log Capture: The Homer module subscribes to log messages via PubSub
  3. Filtering: Only logs containing call_id metadata are forwarded
  4. HEP3 Encoding: Logs are encoded as HEP3 packets with protocol type 100 (log)
  5. Correlation: HOMER correlates logs with SIP traces using the Call-ID

Configuration​

Add the homer_server configuration to your config/runtime.exs:

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

Parameters​

ParameterTypeRequiredDefaultDescription
hostStringYes-HOMER server IP address or hostname
portIntegerNo9060HEP receiver UDP port
auth_keyStringNonilOptional HEP authentication key. Set to match authkey in heplify-server config if enabled
capture_idIntegerNo2001Capture agent identifier. Appears in HOMER UI to identify the log source

Disabling HOMER Integration​

To disable HOMER integration, either:

  • Remove the homer_server configuration entirely, or
  • Comment out the configuration block

When disabled, the Homer module is not started and no logs are forwarded.

HOMER Server Requirements​

The HOMER server must be running heplify-server with HEP reception enabled on UDP.

heplify-server Configuration​

Verify your heplify-server.toml includes:

HEPAddr = "0.0.0.0:9060"

Supported Protocol Types​

OmniTAS sends logs with HEP protocol type 100, which heplify-server routes to logs_capture. Ensure your HOMER database schema supports log storage.

Log Correlation​

Automatic Call-ID Injection​

OmniTAS automatically injects the Call-ID into Logger metadata during:

  • MO Call Processing: When processing mobile-originated calls
  • MT Call Processing: When processing mobile-terminated calls
  • Call Events: When handling answer and hangup events

Log Format​

Logs sent to HOMER include:

FieldDescription
Correlation IDSIP Call-ID for trace correlation
TimestampMicrosecond-precision timestamp
LevelLog level (debug, info, warning, error)
MessageLog message content
Source IPOmniTAS server IP address
Capture IDConfigured capture agent identifier

Example Log in HOMER​

After a call is processed, HOMER displays correlated data:

[info] Processing MO call from: 61400123456 to: 61400654321
[debug] Sh lookup for caller: 61400123456
[info] OCS authorization: GRANTED (120 seconds)
[debug] Setting variable: hangup_case = none

These logs appear alongside the SIP INVITE, 200 OK, and BYE messages in the HOMER call detail view.

HEP3 Protocol Details​

OmniTAS implements HEP3 as defined by the HOMER project, compatible with Kamailio's siptrace module.

Chunk Types Used​

Chunk IDNameDescription
0x0001IP FamilyAlways 2 (IPv4)
0x0002IP ProtocolAlways 17 (UDP)
0x0003Source IPv4OmniTAS server address
0x0004Dest IPv4HOMER server address
0x0007Source Port0 (not applicable for logs)
0x0008Dest PortConfigured HEP port
0x0009Timestamp SecUnix timestamp seconds
0x000ATimestamp USecMicroseconds component
0x000BProtocol Type100 (log)
0x000CCapture IDConfigured capture_id
0x0011Correlation IDSIP Call-ID
0x000FPayloadLog message
0x000EAuth KeyOptional authentication

Troubleshooting​

Logs Not Appearing in HOMER​

Symptoms: Calls complete successfully but no logs appear in HOMER

Possible causes:

  • HOMER server unreachable on configured port
  • Firewall blocking UDP traffic to port 9060
  • heplify-server not configured to receive HEP
  • Logs missing call_id metadata

Resolution:

  1. Verify network connectivity: nc -zvu <homer_host> 9060
  2. Check heplify-server is listening: ss -ulnp | grep 9060
  3. Review heplify-server logs for incoming packets
  4. Verify call_id appears in OmniTAS logs (check for call_id= in log output)

Authentication Failures​

Symptoms: heplify-server logs show authentication errors

Possible causes:

  • Mismatched auth_key between OmniTAS and heplify-server
  • Auth key configured on one side but not the other

Resolution:

  1. If heplify-server has no auth key configured, set auth_key: nil in OmniTAS
  2. If heplify-server requires auth, configure matching key in both systems

Missing Correlation​

Symptoms: Logs appear in HOMER but are not correlated with SIP traces

Possible causes:

  • Call-ID format mismatch between SIP and logs
  • HOMER correlation configuration

Resolution:

  1. Verify the Call-ID in logs matches the SIP Call-ID header exactly
  2. Check HOMER's correlation settings for the logs_capture table

Metrics​

When HOMER integration is enabled, monitor these indicators:

OmniTAS Logs​

Watch for warnings indicating HEP transmission failures:

[warning] Failed to send HEP packet to Homer: <reason>

heplify-server Metrics​

If Prometheus metrics are enabled on heplify-server, monitor:

  • heplify_packets_total{type="log"} - Total log packets received
  • heplify_packets_dropped_total - Dropped packets (buffer/parse errors)

Architecture Reference​

Component Interaction​

Data Flow​

See Also​