Ingesting Logs To CtrlB via FluentBit

This document provides comprehensive instructions for configuring FluentBit to forward log data to CtrlB instances. FluentBit will be configured to transmit simple JSON log format to your designated instance endpoint.

Connection Parameters

The following parameters are required for establishing connectivity between FluentBit and your CtrlB instance:

• Endpoint URL: http(s)://<INSTANCE_HOST>/api/default/<STREAM_NAME>/_json
• Authentication Method: HTTP Basic Authentication via Authorization header
• Authentication Format: Authorization: Basic <API_TOKEN>
• Timestamp Specification: Unix epoch time in milliseconds within the _timestamp field

Implementation Configurations

File-Based Log Ingestion

This configuration applies to applications that write log files in either JSON or plain text format to the local filesystem.

Configuration File: fluent-bit.conf

[SERVICE]
    Flush        1
    Daemon       Off
    Log_Level    info

[INPUT]
    Name         tail
    Path         /var/log/app/*.log
    Tag          app.*
    # Parser configuration depends on log format:
    # - For JSON formatted logs: omit Parser directive
    # - For plain text logs: omit Parser directive to utilize default field mapping

[OUTPUT]
    Name         http
    Match        app.*
    Host         <INSTANCE_HOST>
    Port         443                 # Port 80 for HTTP connections
    URI          /api/default/<STREAM_NAME>/_json
    Format       json                # Ensures JSON object output per record
    Json_Date_Key _timestamp          # Timestamp field designation
    Json_Date_Format epoch_ms        # Millisecond precision epoch format
    Header       Authorization Basic <API_TOKEN>
    Header       Content-Type application/json
    tls          On                  # Disable for HTTP connections
    tls.verify   On                  # Disable for self-signed certificates

Configuration Notes:

• Applications that already generate _timestamp fields in epoch milliseconds should omit the Json_Date_Key and Json_Date_Format directives to preserve original timestamp values
• Plain text log entries will be automatically mapped to the log field, resulting in JSON objects formatted as {"log":"<log_content>"}

Container Log Processing

This configuration addresses containerized applications using Docker or CRI runtimes that output JSON-formatted log entries to standard output streams.

[SERVICE]
    Flush        1
    Daemon       Off

[INPUT]
    Name         tail
    Path         /var/log/containers/*.log
    Tag          kube.*
    Parser       docker              # Substitute 'cri' for CRI-compatible runtimes
    Mem_Buf_Limit 50MB
    Skip_Long_Lines On

[FILTER]
    Name         parser
    Match        kube.*
    Key_Name     log
    Parser       app_json            # References parser definition below
    Reserve_Data On

[OUTPUT]
    Name         http
    Match        kube.*
    Host         <INSTANCE_HOST>
    Port         443
    URI          /api/default/<STREAM_NAME>/_json
    Format       json
    Json_Date_Key _timestamp
    Json_Date_Format epoch_ms
    Header       Authorization Basic <API_TOKEN>
    Header       Content-Type application/json
    tls          On
    tls.verify   On

[PARSER]
    Name         app_json
    Format       json
    Time_Key     _timestamp           # Modify to match application timestamp field
    Time_Format  %Y-%m-%dT%H:%M:%S.%LZ  # adjust to app’s timestamp format
    Time_Keep    On

Parser Configuration:

• The Time_Key parameter must correspond to the timestamp field name used by your application
• If application logs do not contain timestamp information, retain default configuration to utilize ingestion timestamps

---

Validation Procedures

Service Initialization

Execute the following command to start the FluentBit service:

fluent-bit -c fluent-bit.conf

Test Data Generation

Generate a test log entry to verify configuration:

echo '{"level":"info","job":"my-service","log":"hello from fluent-bit","_timestamp": 1756684800000}' >> /var/log/app/test.log

Verification Process

Access your CtrlB instance dashboard to confirm successful data ingestion. Verify that log entries appear in the designated stream with appropriate timestamps and field mappings.

---

Troubleshooting Guide

Authentication Errors

HTTP 401 Unauthorized

• Root Cause: Invalid or malformed authentication credentials
• Resolution: Verify the Authorization header follows the exact format: Authorization: Basic <API_TOKEN>
• Validation: Confirm the API token is correctly encoded and has not been truncated

Endpoint Configuration Errors

HTTP 404 Not Found

• Root Cause: Incorrect endpoint URI specification
• Resolution: Ensure the URI parameter matches the required format: /<STREAM_NAME>/_json
• Validation: Verify stream name matches your CtrlB instance configuration

Transport Layer Security Issues

TLS Connection Failures

• Root Cause: Certificate validation or port configuration errors
• Resolution Steps:
  1. Verify port configuration (443 for HTTPS, 80 for HTTP)
  2. For development environments with self-signed certificates, set tls.verify Off
  3. Ensure certificate chains are properly configured for production environments
  4. Validate that the instance hostname matches certificate subject names

Timestamp Processing Issues

Missing or Invalid Timestamp Fields

• Root Cause: Timestamp field configuration mismatch
• Resolution Options:
  1. Configure FluentBit to generate timestamps: Add Json_Date_Key _timestamp and Json_Date_Format epoch_ms to output configuration
  2. Application-level timestamps: Ensure application generates numeric epoch millisecond values in the designated timestamp field
  3. Field mapping: Verify Time_Key parameter matches the actual timestamp field name in your log format

Performance Considerations

For high-volume log processing environments:

• Adjust Mem_Buf_Limit based on available system memory
• Configure appropriate Flush intervals to balance latency and throughput
• Monitor FluentBit resource utilization and adjust buffer sizes accordingly
• Implement log rotation policies to prevent disk space exhaustion