Graylog
Overview
What is its Purpose?
Enables collecting Apinizer log events in GELF format at a single central location
Provides log delivery continuity by managing traffic intensity with queue and compression settings
Secures data sent over the log channel with TLS/certificate verification options
Reduces management costs by maintaining Development/Test/Production separation with environment-based parameters
Working Principle
When a Graylog connection is requested from within an Integration Flow or Connector, the system reads the configured connection parameters
Asynchronous send queue separates threads from the connection pool based on maxInflightSends and queueSize values
If TLS is active, mutual TLS and certificate chain verification are applied; otherwise, IP whitelisting is used at network level
GELF messages are encoded according to the selected compression policy and sent to Graylog endpoint via selected transportType (TCP or UDP)
After the operation completes, the connection remains open and returns to the pool; if unused for a long time, tcpKeepAlive setting comes into effect
On connection error, timeout, or authentication error, reconnectDelay duration is waited, event is logged, and detailed error message is shown to the user
Usage Areas
Transferring application logs from all Apinizer nodes to central Graylog cluster
Real-time monitoring of custom function logs in Integration Flow steps (e.g., external API responses)
Providing early warning mechanism by logging Scheduled Job results or gateway health metrics
Feeding data for anomaly detection with special GELF levels to Security/SIEM teams
Technical Features and Capabilities
Basic Features
Leaves reliability/performance balance to the user by allowing selection between TCP and UDP.
Optimizes bandwidth with GZIP, ZLIB, or NONE options.
Ability to define separate connection parameters for each environment (Development, Test, Production).
Activating or deactivating the connection (enable/disable toggle). In passive state, the connection cannot be used but its configuration is preserved.
Advanced Features
Importing and validating PEM-based certificate file through the UI.
Network optimization with tcpNoDelay, tcpKeepAlive, and sendBufferSize values.
Scales high-volume logs with threads and maxInflightSends parameters.
Ability to validate connection parameters before saving using the "Test Connection" button.
Exporting connection configuration as a ZIP file. Importing to different environments (Development, Test, Production). Version control and backup capability.
Monitoring connection health, pool status, and performance metrics.
Connection Parameters
Required Parameters
Description: Connection name (must be unique)
Example Value: Production_Graylog
Notes: Cannot start with a space, special characters should not be used
Description: Published environment ID where logs will be routed
Example Value: prod-env-01
Notes: Registration is blocked if environment is not published
Description: Graylog GELF endpoint DNS/IP address
Example Value: graylog.internal.local
Notes: Use FQDN for production
Description: GELF listener port
Example Value: 12201
Notes: TCP/UDP can share the same port
Description: Connection transport type (TCP/UDP)
Example Value: TCP
Notes: TCP recommended; reliable network required for UDP
Description: GELF message compression policy
Example Value: GZIP
Notes: Bandwidth increases when NONE is selected
Description: Minimum log level
Example Value: WARNING
Notes: Selection provides filtering within Graylog
Description: Log wait queue size on UI side
Example Value: 512
Notes: High values increase RAM consumption
Description: Reconnection delay after interruption
Example Value: 2500
Notes: In milliseconds
Description: Wait time while establishing connection
Example Value: 10000
Notes: Adjust according to network delays
Description: TCP send buffer size
Example Value: -1
Notes: -1 uses system default
Description: Concurrent send count
Example Value: 512
Notes: Excessive values can create pressure on Graylog side
Description: Background log sending thread count
Example Value: 0
Notes: 0 automatically adjusts according to CPU cores
Optional Parameters
Description: Description about connection purpose
Default Value: (Empty)
Recommended Value: Prod log forwarding for CoreAPI
Description: TLS usage in GELF traffic
Default Value: false
Recommended Value: true (Production)
Description: Server certificate verification
Default Value: false
Recommended Value: true (Production)
Description: PEM certificate chain file
Default Value: (Empty)
Recommended Value: graylog-ca.pem
Description: Disables Nagle algorithm
Default Value: true
Recommended Value: true
Description: Preserves passive connections
Default Value: false
Recommended Value: true (remote DC)
Description: Adds Apinizer metadata to GELF extra fields
Default Value: true
Recommended Value: true
Description: Adds Apinizer context to message body
Default Value: true
Recommended Value: true
Timeout and Connection Pool Parameters
Description: Maximum wait time for connection establishment
Default: 10000
Min: 1000 | Max: 60000
Unit: milliseconds
Description: Maximum wait time for request response
Default: N/A
Min: - | Max: -
Unit: milliseconds
Description: Maximum number of connections in the connection pool
Default: Determined by threads value
Min: 1 | Max: 64
Unit: count
Description: Reconnection interval
Default: 2500
Min: 500 | Max: 60000
Unit: milliseconds
Usage Scenarios
Situation: Core API gateway produces errors under high traffic
Solution: TransportType=TCP, Compression=GZIP, GelfLevel=ERROR
Expected Behavior: Only error logs appear on Graylog side, bandwidth is optimized
Situation: Security team wants critical alarms
Solution: GelfLevel=ALERT, AppendToAttributes=true
Expected Behavior: SIEM enriches alarm context thanks to extra attributes
Situation: Latency measurements will be carried via UDP
Solution: TransportType=UDP, QueueSize=256
Expected Behavior: Logs are sent with low latency, possible losses are accepted
Situation: Connecting to remote data center with TLS
Solution: TLS Enabled=true, TLS Cert Verification=true, upload certificate
Expected Behavior: Encrypted channel is established, self-signed certificates are rejected
Situation: Night jobs produce many logs in a short time
Solution: QueueSize=2048, Threads=8, MaxInflight=1024
Expected Behavior: Log transfer completes without queue overflow
Situation: Verbose logging in test environment
Solution: GelfLevel=DEBUG, Compression=NONE
Expected Behavior: All logs are transmitted uncompressed for troubleshooting
Connection Configuration
Creating a New Graylog Connection
Configuration Steps
- Go to Connection → Graylog from the left menu.
- Click the [+ Create] button in the top right.
Enable Status (Active Status):
- Set active/passive status with toggle. New connections are active by default.
Name (Name) - Required:
- Example:
Production_Graylog - Enter unique name, cannot start with space.
- System automatically checks. Green checkmark: available. Red X: existing name.
Description (Description):
- Example: "Graylog prod ingestion"
- Max. 1000 characters.
- Describe the connection's purpose.
In the action button area at the top of the page, you can use the [<> Variable] button to select dynamic values, and with global variables, you can manage connection parameters with variable-based values instead of fixed values. For detailed information, review the Dynamic Variables page.
- Select environment from dropdown menu: Development, Test, or Production.
- Different connection parameters can be defined for each environment.
- Hostname & Port: Enter Graylog GELF listener information.
- TransportType: Select TCP (reliable) or UDP (low latency).
- CompressionType: Determine GZIP/ZLIB/NONE options according to latency and CPU.
- Wrong hostname causes log loss.
- GELF Message Level: Select appropriate level from Debug to Emergency.
- QueueSize, Threads, MaxInflightSends: Set values according to log volume.
- Append options: Determine whether Apinizer metadata will be included in logs.
- ConnectTimeout & ReconnectDelay: Determine in milliseconds according to network conditions.
- SendBufferSize: -1 uses system default, enter byte value in custom fields.
- Increase threads value to prevent Pool exhausted warning in heavy traffic.
- TLS Enabled: Required in Production.
- TLS Cert Verification Enabled: Upload certificate when verification is enabled.
- TLS Trust Cert Chain File: Upload PEM file from UI, maximum 100 MB.
- Click the [Test Connection] button.
- Test whether connection parameters are correct.
- Successful: Green confirmation message
- Failed: Error details are shown
- Click the [Save and Deploy] button in the top right.
Checklist:
- Unique name
- Required fields filled
- Test connection successful (recommended)
Result:
- Connection is added to list
- Becomes available for use in Integration Flow and Connector steps
- Becomes active according to environment
Connection successfully created! You can now use it in Integration Flow and Connector steps.
Deleting Connection
Select Delete from the ⋮ menu at the end of the row or click the [Delete] button on the connection detail page
Check Before Deleting: May be in use in Integration Flow or Connector steps. If necessary, assign an alternative connection. Take a backup with Export before deleting
Instead of deleting, use the Disable option. Connection becomes passive but is not deleted. Can be reactivated when needed
Exporting/Importing Connection
In this step, users can export (export) existing connections for backup, moving to different environments, or sharing purposes, or import (import) a previously exported connection again. This operation is used to maintain data integrity in version control, transitions between test and production environments, or inter-team sharing processes.
Export
Select ⋮ → Export from the action menu. ZIP file is automatically downloaded.
Click the [Export] button on the connection detail page. ZIP file is downloaded.
Format: Date-connection-ConnectionName-export.zip
Example: 13 Nov 2025-connection-Production_Graylog-export.zip
- Connection JSON file
- Metadata information
- Dependency information (e.g., certificates, key store)
- Backup
- Moving between environments (Test → Prod)
- Versioning
- Team or project-based sharing
Import
- Click the [Import Graylog] button on the main list.
- Select the downloaded ZIP file.
- System checks: Is format valid? Is there a name conflict? Are dependencies available?
- Then click the [Import] button.
Scenario 1: Name Conflict → Overwrite the old connection or create with a new name.
Scenario 2: Missing Dependencies → Create missing certificates or key stores first or remove them during import.
Connection Usage Areas
Steps:
- Create the connection
- Verify the connection with Test Connection
- Save and activate with Save and Deploy
- Ensure the connection is in Enabled status
Select Graylog Connection in steps requiring log sending. Examples: steps like "Send Message", "Custom Log", "Notify SIEM". Connection selection is made from the Connection field in these steps' configuration
In scheduled tasks (e.g., health check log every 5 minutes), access external systems by selecting Graylog Connection. When connection changes, job behavior uses new parameters
Connection accuracy can be checked independently of Integration Flow using the Connection Test feature. This test is critical in the debugging process
Best Practices
Things to Do and Best Practices
Bad: Different GELF field names in each step
Good: Using common field names
Best: Making Apinizer context attributes mandatory and validating with Graylog pipeline
Bad: Selecting NONE in all environments
Good: Using GZIP in Production
Best: Determining dynamic policy according to traffic and monitoring decompress cost on Graylog side
Bad: Sending critical logs via UDP
Good: Using TCP in Prod, UDP in Test
Best: Making TCP + TLS mandatory, using UDP only for low-risk metrics
Bad: Leaving QueueSize value too low
Good: Setting between 512-1024 according to traffic analysis
Best: Updating queue/buffer settings automatically according to peak load measurements
Bad: Using the same connection parameters in all environments
Good: Creating separate connections for each environment
Best: Managing all environments in a single connection using the Environment option, only changing environment when transitioning between environments
Bad: Saving and deploying connection without testing
Good: Verifying with Test Connection before saving
Best: Testing after every parameter change, performing full integration test in test environment before going to production
Security Best Practices
Obtain certificate chains only from trusted sources. Monitor expiration dates, upload new file before renewal
Make Graylog endpoint accessible only from necessary Apinizer subnets; apply allowlist in firewall
If personal data or access tokens are being logged, sanitize GELF messages; add masking rules in Apinizer policies
Store sensitive information such as usernames and passwords using environment variables or secret manager. Do not hardcode credentials in code or configuration files. Update passwords periodically
Always enable SSL/TLS in production environment. Use self-signed certificates only in development environment. Track certificate expiration dates and renew them on time
Allow only authorized users to change connection configuration. Store connection change logs. Apply change approval process for critical connections
Things to Avoid
Why to avoid: UDP packet loss leads to loss of critical events
Alternative: Use TCP + TLS
Why to avoid: Unnecessary DEBUG levels bloat Graylog storage
Alternative: Determine level according to business need, add pipeline filters
Why to avoid: Expired certificate drops TLS connection
Alternative: Renew certificates with calendar reminders
Why to avoid: Test data may be written to production system, real users may be affected, security risk occurs
Alternative: Create separate connections for each environment, use environment parameter, separate connection names by adding prefix according to environment (Test_, Prod_)
Why to avoid: Connection continuously times out in network delays, Integration steps fail
Alternative: Set timeout values according to real usage scenarios, measure network latency and set timeouts accordingly
Why to avoid: New connection opens with each request, performance decreases, resource consumption increases, target system load increases
Alternative: Enable connection pool, set pool size according to traffic volume, set up pool monitoring
Performance Tips
Recommendation: Use QueueSize value as single send batch, adjust according to Graylog capacity
Effect: Latency decreases, throughput increases
Recommendation: Plan transitions to ZLIB or NONE instead of GZIP by tracking CPU, plan slowdowns
Effect: CPU consumption is balanced, log latency decreases in critical periods
Recommendation: Limit threads value to 50% of active CPU cores, scale horizontally if needed
Effect: System resources remain balanced, throttling decreases
Recommendation: Set pool size according to peak traffic (recommended: concurrent request count × 1.5), set idle connection timeouts, perform pool health check
Effect: Connection opening cost decreases by 80%, response times decrease, resource usage is optimized
Recommendation: Measure real network latency, set timeout values accordingly, avoid very low or very high timeouts
Effect: Unnecessary waits are prevented, fast fail-over is provided, user experience improves
Recommendation: Monitor connection pool usage, track timeout rates, perform connection health check, set up alerting
Effect: Problems are proactively detected, performance bottlenecks are identified early, downtime decreases
Troubleshooting
GELF Message Rejected
Message size exceeds 1 MB, JSON fields may be wrong type, or Graylog pipeline error may exist.
Reduce large fields in message.
Check JSON schema.
Review Graylog pipeline logs.
TLS Handshake Failed
Certificate chain missing, hostname mismatch, or TLS disabled server may exist.
Re-upload certificate file.
Verify hostname matches CN/SAN.
Check Graylog server TLS settings.
Connection Timeout
Network delay, target system responding slowly, or timeout value may be too low.
Check network connectivity.
Check target system health.
Increase timeout values.
Review connection logs.
Authentication Failed
Wrong username/password, expired credentials, or permission problem may exist.
Verify credentials.
Check that the user is active in the target system.
Check that necessary permissions are granted.
Check SSL/TLS certificates.
Pool Exhausted
Pool size may be too low, connection leak may exist, or traffic may be too high.
Increase pool size.
Check that connections are properly closed.
Set idle connection timeouts.
Monitor connection usage metrics.
Connection Test Successful But Integration Flow Errors
Different connection may be selected in Integration/Connector step, step may be misconfigured, or Flow/Job may not be redeployed.
Check that the connection's enable toggle is active.
Verify that the correct connection is selected in Integration Flow.
Redeploy the connection.
Redeploy Integration Flow or Job.
Check Gateway logs.
Frequently Asked Questions (FAQ)
How many projects can Graylog Connection be shared in?
Connections created as Admin are global and can be used by all projects; those created at project level are only visible in the related project.
How many environments can connect to Graylog at the same time?
Separate entries can be made for each environment; environment list is loaded from Environment service and only published environments can be selected.
What format should TLS certificate file be in?
PEM chain is supported; uploaded file cannot exceed 100 MB limit and must contain BEGIN CERTIFICATE block.
Do I need to redeploy when changing GELF transport?
Yes, TransportType change redeploys the connection; if Graylog listener is not compatible, change fails.
Should I set log level in Graylog or in Connection?
gelfMessageLevel in Connection determines minimum threshold, Graylog pipelines can do additional filtering; manage both together.
Can I use the same connection in multiple Integration Flows?
Yes, the same connection can be used in multiple Integration Flow or Connector steps. This provides central management and guarantees configuration consistency. However, changes made to the connection will affect all usage locations, so care should be taken.
Is using connection pool mandatory?
Using connection pool is not mandatory but strongly recommended in high-traffic systems. Reusing existing connections instead of opening new ones with each request significantly increases performance.
Should I create different connections for Test and Production?
Yes, it is recommended to create separate connections for each environment. Alternatively, you can manage all environments within a single connection using the environment parameter. This approach provides easier management and less error risk.
Test Connection is successful but not working in Integration Flow, why?
Several reasons may exist:
- Connection enable toggle may be passive
- Different connection may be selected in Integration step
- Connection may not be deployed
- Integration Flow may not be redeployed yet