Skip to main content
Version: 6.2

Diagnosing SAF Beat and SAF Beat Manager Issues

This article describes how to diagnose SAF Beat agents and SAF Beat Manager (SBM). Log examples follow the format of real messages. Code line numbers (for example, client.go:88) may differ between versions, so rely on the message text and logger name.

Conventions​

Service Status​

Check service status on the agent and SAF Beat Manager hosts:

systemctl status safBeat.service
systemctl status safBeatManager.service

Example during normal operation:

● safBeat.service - SAFBeat
   Loaded: loaded (/etc/systemd/system/safBeat.service; enabled; vendor preset: disabled)
   Active: active (running) since Tue 2026-10-07 09:00:12 UTC; 2h 14min ago
 Main PID: 18422 (safBeat)

Example of a failure: the service cannot start and keeps restarting:

● safBeat.service - SAFBeat
   Loaded: loaded (/etc/systemd/system/safBeat.service; enabled; vendor preset: disabled)
   Active: activating (auto-restart) (Result: exit-code) since Tue 2026-10-07 11:22:40 UTC; 4s ago
  Process: 20911 ExecStart=/app/safBeat/safBeat (code=exited, status=1/FAILURE)

What to Do​

  1. Find the cause in the service log (see Logs): a configuration error, an unavailable certificate, or a port already in use

  2. Fix the cause and restart the service

    systemctl restart safBeat.service

  3. If the service remains in activating (auto-restart), stop it with systemctl stop safBeat.service, fix the cause, and start it again. Frequent restarts add load and log entries

Logs​

  • the SAF Beat log directory is set by rotation.log_path in ${SB_HOME}/config/config.yaml, by default ${SB_HOME}/logs. The log level is set by rotation.log_level (trace, debug, info, warn, error, fatal)
  • the SAF Beat Manager log directory is set by logs.logPath, by default ${SBM_HOME}/logs

For detailed diagnostics, temporarily set the log level to debug and restart the service.

Example SAF Beat log entry for a successful connection to SAF Beat Manager:

2026-10-07T09:00:15.221Z INFO manager/client.go:88 successfully connected to SAF Beat Manager 192.0.2.10:7767

Agent Connection Issues​

If a SAF Beat agent does not appear in SAF Beat Management or appears inactive, perform the checks below in order.

Agent Connection to SAF Beat Manager​

The agent connects to SAF Beat Manager through the port set by manager.port (default 7767). Check that the port is reachable from the agent host and that its configuration contains the correct address. Example log entry when the network is unreachable:

2026-10-07T11:22:41.015Z ERROR manager/client.go:102 failed to connect to SAF Beat Manager 192.0.2.10:7767: dial tcp: i/o timeout

What to Do​

Allow connections through manager.port in the firewall between the agent and SAF Beat Manager hosts, or set the correct address and port in the agent configuration. Restart SAF Beat after changing the configuration.

TLS Certificates​

If ssl.enable: true is set, a mismatched or expired agent certificate causes a connection error. Check the SAF Beat log for certificate validation errors. The paths to the agent certificates and key are set by ssl.cert_ca, ssl.node_cert, and ssl.node_key in ${SB_HOME}/config/config.yaml (default - ${SB_HOME}/cert/). On the SAF Beat Manager side, ssl.safBeatTLSLevel in ${SBM_HOME}/etc/config.yml controls client certificate validation, while ssl.certPath in the same file sets the SAF Beat Manager certificate path (default - ${SBM_HOME}/etc/ssl/). Example log entry for a certificate error:

2026-10-07T11:25:03.552Z ERROR manager/client.go:102 failed to connect to SAF Beat Manager: x509: certificate signed by unknown authority

To diagnose the issue without disabling certificate validation, check the certificate chain from the agent host:

openssl s_client -connect <saf_beat_manager_host>:7767 -CAfile <path to CA certificate>

The command shows a certificate chain error, if present, without changing the SAF Beat configuration.

What to Do​

Reissue or copy valid CA and agent certificates and the SAF Beat private key to the paths set by ssl.cert_ca, ssl.node_cert, and ssl.node_key (see Using Pre-Generated Certificates). Then restart the service.

Note!

Disabling certificate validation (ssl.verify: false) may confirm the cause but does not resolve it. Do not leave validation disabled in production. Use this setting only briefly for diagnosis, or check the certificate with openssl s_client without changing the configuration.

Agent Status in the Interface​

On the SAF Beat Management page, check the client fields: Connection should be Online, and Health should be No Errors. Offline in Connection means the agent is not connected to SAF Beat Manager (see Agent Connection to SAF Beat Manager and TLS Certificates). Error in Health indicates an issue with the agent or its applications, unrelated to the network or certificates.

What to Do​

If the network and certificates are working but the agent remains inactive, restart the SAF Beat service on its host and check again.

Data Delivery from Agents to Data Collector or Data Storage​

SAF Beat sends collected data to SAF Monitor Data Collector (hereinafter Data Collector) through a pipeline with a SAF Beat input, or directly to SAF Monitor Data Storage (hereinafter Data Storage). The destination is determined by the output settings in the application configuration distributed to the agent through SAF Beat Manager.

An application such as Winlogbeat runs as a separate process started by SAF Beat and writes to its own log. Example of a dropped Data Collector connection in the application log:

{"log.level":"error","@timestamp":"2026-10-08T12:06:59.598+0300","log.logger":"logstash","log.origin":{"function":"github.com/elastic/beats/v7/libbeat/outputs/logstash.(*msgRef).dec","file.name":"logstash/async.go","file.line":280},"message":"Failed to publish events caused by: write tcp 198.51.100.15:51970->192.0.2.70:5044: wsasend: An existing connection was forcibly closed by the remote host.","service.name":"winlogbeat","ecs.version":"1.6.0"}

wsasend: An existing connection was forcibly closed by the remote host means the remote side closed the connection: Data Collector or an intermediate firewall or load balancer. Start diagnosis on the Data Collector side using the port shown.

Another example: connection refused rather than a dropped established connection:

{"log.level":"error","@timestamp":"2026-10-03T01:22:27.304Z","log.logger":"publisher_pipeline_output","log.origin":{"function":"github.com/elastic/beats/v7/libbeat/publisher/pipeline.(*netClientWorker).run","file.name":"pipeline/client_worker.go","file.line":148},"message":"Failed to connect to backoff(async(tcp://192.0.2.71:5045)): dial tcp 192.0.2.71:5045: connect: connection refused","service.name":"auditbeat","ecs.version":"1.6.0"}

connection refused means no service is listening on the specified address and port. Unlike forcibly closed, the connection is never established. Check that Data Collector is running and accepting connections on that address and port, and that the application configuration contains the same values.

What to Do​

  • check the application configuration distributed to the agent (the Apps section on the SAF Beat Management page): output must point to a reachable Data Collector or Data Storage address
  • check the receiving component's availability and status (see Diagnosing Data Collector Issues or Diagnosing Data Storage Issues)
  • check whether the agent (ElasticBeat) version is compatible with the Data Collector version (see Installing SAF Beat Manager); if not, upgrade ElasticBeat to the recommended version

Application Cannot Find the Agent Distribution Package​

A Beat-type application is distributed to the agent with an archive of the corresponding distribution package (see Binaries). If the agent cannot identify the required package, the expanded client card displays no beat for it app in the status error section.

What to Do​

  1. In the expanded client card, check List of binaries: an archive for the required agent type must be uploaded. For example, a Winlogbeat application requires an archive such as winlogbeat-*.zip

  2. If the archive is uploaded, check the application logs. If there are no log entries, the application has not started; continue to the next step

  3. Check the Name field under Apps: the application name must start with the agent type even if the distribution archive has the correct name. A common mistake is a name starting with windows instead of winlogbeat. Matching examples

    • the archive winlogbeat-8.13.4-windows-x86_64.zip requires an application name starting with winlogbeat
    • the archive filebeat-9.4.2-linux-x86_64.tar.gz requires a name starting with filebeat

    If the application name starts differently, add the agent type to its beginning and redeploy the application to the agent