Debug Commands

The Falcon LogScale Collector Debug API supports the following commands:

Command Description
Monitor This command enables you to see a live view of the running state of the Falcon LogScale Collector.
Query These commands allows you to query using one of the following arguments:

  • metrics: returns the metrics as a JSON object.

  • internallogs: fetches debug log of a running Log Collector through the local API.

Export This command exports an all-in-one debug file which can be used for troubleshooting.
Ping This command tests connectivity to your Fleet Management infrastructure by:

  • Reading and validating your configuration file

  • Resolving DNS entries for your Fleet Management server

  • Testing direct connections to all resolved IP addresses

  • Verifying TLS handshakes and certificate trust chains

The local API used to access these commands is enabled by default and listens on:

  • Windows: Named pipe which is restricted to administrators

  • Linux and macOS: Unix socket located inside the data directory, restricted to the service user and group

To disable the local API, add the following to the config file:

yaml
api:
  enabled: false
Query Internal Logs and Metrics

The query command can be used to query metrics or internal logs:

Internal Logs

The internallogs command fetches the debug log of a running Falcon LogScale Collector through the local API, without having to restart or reconfigure the service. The debug log via local API is unfiltered, and is not affected by --log-level, logLevel or the internal debug log sender feature.

shell
logscale-collector query internallogs --cfg <path to config>
Metrics

The metrics command returns the metrics of pipelines for collecting data. The metrics include meters and gauge describing the flow of data through the Log Collector.

The metrics can be retrieved as JSON via:

shell
logscale-collector query metrics --cfg <path to config>
Export Internal Logs

This command can help troubleshoot an installation by creating an all-in-one debug file that can be shared with support.

The export-debug command connects to the local API to pull the running state, metrics and debug log without disturbing the running sources and sinks. The command creates a file called debug.zip in the current directory. The file contains the following information:

  • The fleet management mode and server URL listed in the configuration file.

  • The errors and warnings emitted from parsing the configuration file.

  • The running version of the LogScale Collector service.

  • The id of the LogScale Collector service.

Additionally, you can run commands to export metrics and internal logs.

Run the following command to export the debug file:

shell
logscale-collector export-debug --cfg <path to config>
Use Ping to test connectivity

The ping command is available in Falcon LogScale Collector from version 1.11.

This command simplifies the troubleshooting of connectivity issues between the Log Collector and your Fleet Management servers. It provides administrators with the ability to verify the TLS configuration, certificate trust chains, and network connectivity, all in a single command.

Basic Usage
shell
sudo logscale-collector ping --cfg /etc/logscale-collector/config.yaml
Understanding the Output

Successful Connection

When you run the ping command, you'll see detailed information about each connection attempt. The example below shows successful connections with no issues:

shell
✓ Config file read successfully: /etc/logscale-collector/config.yaml
→ Fleet management type: full
→ Server URL: https://flc-api.example.com
→ Resolving IP addresses for: flc-api.example.com
→ Found 2 IP address(es): 192.0.2.10 192.0.2.11
→ Testing connections to each IP address:
  → Connecting to 192.0.2.10:443... ✓ Success: Connected with ID abc123xyz...
    TLS Version: TLS 1.3
    Ciphersuite: TLS_AES_256_GCM_SHA384 (X25519)
    Certificate:
      ↳ Example Root CA
        ↳ Example Intermediate CA
          ↳ flc-api.example.com
            Serial: 123456789012345678901234567890
            Valid from: 2025-03-03 00:00:00 +0000 UTC
            Valid to: 2026-03-02 23:59:59 +0000 UTC
            Fingerprint (SHA-256): a1b2c3d4e5f6...
            Algorithm: RSA
✓ All connection tests completed successfully!
Common Error Scenarios

Network Timeout

shell
→ Connecting to 192.0.2.10:443... ✗ Timed out

A Timed out error indicates that firewall rules or network routing issues are preventing connectivity.

Certificate Trust Issues

shell
→ Connecting to 192.0.2.10:443... ✗ Certificate is not trusted
    Example Intermediate CA

A Certificate is not trusted error indicates that the system doesn't trust the Certificate Authority (CA). If you see this error, confirm that your CA bundle is properly installed.

Proxy Configuration Problems

shell
→ Detected proxy URL: http://proxy.example.com:3128
→ Testing connection via proxy:
  → Connecting to flc-api.example.com:443... ✗ Connection failed: 
    Could not connect to proxy: dial tcp: lookup proxy.example.com on 
    198.51.100.1:53: no such host

A Could not connect to proxy error indicates that the configured proxy server cannot be reached or resolved.

Proxy Support

The ping command automatically detects and tests proxy configurations. When a proxy is configured, it validates connectivity through the proxy infrastructure:

shell
→ Detected proxy URL: http://proxy.example.com:3128
→ Testing connection via proxy:
  → Connecting to flc-api.example.com:443... ✓ Success
Best Practices

  • Use ping as a first step when troubleshooting collection issues.

  • Include all output generated by the command if you need to open a support ticket. Doing so helps to provide faster problem resolution.