Observability

KubeVoIP keeps observability vendor-neutral. Managed components write useful operational logs to their container stdout or stderr streams so cluster operators can choose Fluent Bit, Vector, Promtail, OpenTelemetry Collector, cloud-native agents, or any other Kubernetes log pipeline.

KubeVoIP does not deploy a logging backend. It provides predictable log output and optional HEP export so each installation can use its own retention, indexing, alerting, and access-control model.

Container logs#

Kamailio logs safe SIP summary events with the kubevoip_sip_event marker. These lines include fields such as namespace, gateway, stage, SIP method, Call-ID, source address, route target, and selected target kind. They do not log raw SIP passwords, HA1 values, or Secret-backed trunk credentials.

Example:

kubevoip_sip_event namespace=telephony gateway=main stage=route_selected method=INVITE call_id=... source=203.0.113.20 target=100 target_kind=SIPUser

RTPengine runs in the foreground with stderr logging enabled. KubeVoIP also logs a kubevoip_rtp_event startup line with the selected advertised address, pod address, and media port range for each relay replica.

Asterisk workers mount an explicit logger.conf so notice, warning, error, and verbose messages are sent to the console.

Useful commands:

kubectl -n telephony logs deploy/main-sip-gateway -c kamailio
kubectl -n telephony logs deploy/main-rtpengine-0 -c rtpengine
kubectl -n telephony logs statefulset/apps-asterisk-pool -c asterisk

To filter SIP summary logs with plain Kubernetes tooling:

kubectl -n telephony logs deploy/main-sip-gateway -c kamailio \
  | grep kubevoip_sip_event

HOMER and HEP capture#

KubeVoIP can send SIP capture traffic from Kamailio to a HOMER or HEP-compatible collector. KubeVoIP does not deploy or operate HOMER; the collector is user-owned infrastructure.

Example SIPGateway capture configuration:

apiVersion: kubevoip.com/v1alpha1
kind: SIPGateway
metadata:
  name: home
spec:
  databaseSecretRef:
    name: kubevoip-db
  networkProfileRef:
    name: public
  mediaRelayRef:
    name: home
  observability:
    capture:
      enabled: true
      type: Homer
      hepAddress: homer-heplify.telemetry.svc.cluster.local
      hepPort: 9060
      hepTransport: udp
      captureMode: transaction
      includePayload: true

captureMode can be transaction or dialog. HOMER capture is disabled by default because SIP and SDP payloads can contain caller identity, endpoint addresses, Contact headers, routing metadata, and other customer-sensitive information.

Supported destinations include in-cluster heplify-server, external HOMER installations reachable from Kamailio pods, and other HEP-compatible collectors.

After enabling capture, reconcile the gateway and check that the generated Kamailio configuration includes siptrace:

kubectl -n telephony get configmap home-sip-gateway-config \
  -o jsonpath='{.data.kamailio\.cfg}' | grep siptrace

Then place a test call or registration and search for the SIP Call-ID in HOMER. The same Call-ID should also appear in the safe kubevoip_sip_event summary logs from the Kamailio container.

Capture modes#

Use transaction for the default troubleshooting path. It captures SIP messages around Kamailio transaction handling and is the best first choice for registrations, challenges, INVITEs, failures, and routing investigations.

Use dialog when you need dialog-oriented call tracing. This is more useful for full call-flow analysis, but should be enabled deliberately because it can capture more customer-sensitive signaling context.

Security notes#

Container summary logs are designed to avoid raw credentials. HOMER capture is different: it intentionally forwards SIP/SDP payloads to the configured capture collector. Treat the collector, its storage, and its UI as sensitive production systems.

Before enabling capture, confirm:

• Kamailio pods can reach the HEP collector address and UDP port.
• The collector has retention limits appropriate for SIP payloads.
• Access to HOMER is restricted to operators who are allowed to inspect call signaling.
• Your logging pipeline does not copy full capture payloads into a broader, less restricted log store.