Skip to main content

CtrlB Logs Ingestion API QuickStart Guide

This documentation provides verification procedures to confirm that your CtrlB instance is properly configured and operational for receiving application telemetry data. The following procedures validate instance connectivity using simple JSON log format (excluding OTLP protocol).

Prerequisites​

Your CtrlB implementation team has provided the following authentication credentials and configuration parameters:

Required Configuration Parameters​

  • Instance Host: <INSTANCE_HOST>
  • API Authentication Token: <API_TOKEN>
  • Stream Identifier: <STREAM_NAME>

Important: Contact your designated CtrlB representative or reference your onboarding documentation if credentials cannot be located.

Data Ingestion Validation​

JSON Log Transmission Test​

Execute the following cURL command to transmit a test JSON log entry to your CtrlB instance:

curl -k "https://<INSTANCE_HOST>/engine/api/default/<STREAM_NAME>/v2/_json_evolving" \
  -H "Authorization: Basic <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[{"level":"info","job":"test","log":"test message for ctrlb"}]'

Expected System Response​

A successful data transmission will generate one of the following HTTP response codes:

  • 200 OK - Data successfully received and processed by the system

Processing Note: Data may require up to 5 minutes to appear in the dashboard interface. Refresh the dashboard or expand the time range filter if data does not appear immediately.

Diagnostic Procedures​

HTTP Error Response Resolution​

401 Unauthorized

  • Root Cause: Authentication token validation failure
  • Resolution: Verify the accuracy and completeness of the <API_TOKEN> parameter

403 Forbidden

  • Root Cause: Insufficient authorization permissions for the specified instance or stream
  • Resolution: Confirm the instance URL and stream name parameters match your account configuration

404 Not Found

  • Root Cause: Malformed or incorrect endpoint URL specification
  • Resolution: Ensure the endpoint path follows the required format: <STREAM_NAME>/v2/_json_evolving

413 Payload Too Large

  • Root Cause: Request payload exceeds configured size limitations
  • Resolution: Implement data batching size reduction and/or enable gzip compression for payload optimization

Dashboard Visibility Troubleshooting​

If HTTP requests return success codes but telemetry data remains absent from the dashboard:

  1. Time Range Configuration: Expand the dashboard time filter to encompass the previous 15-30 minutes
  2. Service Filter Validation: Confirm that active service name filters are not excluding test data entries
  3. Service Name Identification: Search for automatically generated service names such as quickstart-app
  4. Browser State Refresh: Perform a complete browser refresh to eliminate caching issues

Technical Support Resources​

For technical assistance and implementation support:

  • Technical Support Email: support@ctrlb.ai
  • Documentation Portal: Available through your CtrlB account dashboard

Support Availability: Your assigned CtrlB technical team provides comprehensive implementation support throughout the deployment process.