Go SDK

Official Go SDK for LogFlux with encrypted logging, resilient architecture, and production-ready features

The LogFlux Go SDK provides a secure, high-performance way to send encrypted logs to LogFlux from your Go applications.

📚 View full documentation and examples on GitHub →

Installation

1

go get github.com/logflux-io/logflux-go-sdk

Quick Start

Ultra-Simple Usage (2 lines!)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


package main

import logflux "github.com/logflux-io/logflux-go-sdk"

func main() {
    // Initialize LogFlux (one time setup)
    logflux.Init("https://<customer-id>.ingest.<region>.logflux.io", "my-app", "lf_your_api_key", "your-secret")
    defer logflux.Close()

    // Use it with proper log levels
    logflux.Info("User login successful")
    logflux.Warning("Rate limit approaching")
    logflux.Error("Database connection failed")
}

Production-Ready Setup

1
2


export LOGFLUX_API_KEY="lf_your_api_key"
export LOGFLUX_SERVER_URL="https://<customer-id>.ingest.<region>.logflux.io"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


package main

import (
    "github.com/logflux-io/logflux-go-sdk/pkg/client"
    "time"
)

func main() {
    // Create resilient client from environment variables
    client, err := client.NewResilientClientFromEnv("production-server", "your-encryption-secret")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()
    
    // Send logs - they're queued and sent asynchronously
    client.Info("Application started successfully")
    client.Error("Database connection failed - will retry")
    
    // Check statistics
    stats := client.GetStats()
    log.Printf("Sent: %d, Failed: %d, Queued: %d", 
        stats.TotalSent, stats.TotalFailed, stats.QueueSize)
    
    // Flush ensures all logs are sent before shutdown
    client.Flush(10 * time.Second)
}

Key Features

Strong Encryption: AES-256-GCM encryption via RSA handshake
Standardized Log Levels: Full support for Emergency through Debug levels
Resilient Architecture: In-memory queuing, automatic retries, failsafe mode
High Performance: Async processing with configurable worker pools
Built-in Statistics: Monitor performance and queue health
Logger Adapters: Drop-in replacements for log, logrus, zap, and zerolog

Configuration

Environment Variables

1
2
3
4
5
6
7
8
9


# Required
export LOGFLUX_API_KEY="lf_your_api_key"
export LOGFLUX_SERVER_URL="https://<customer-id>.ingest.<region>.logflux.io"

# Optional
export LOGFLUX_QUEUE_SIZE="1000"
export LOGFLUX_FLUSH_INTERVAL="5"        # seconds
export LOGFLUX_WORKER_COUNT="2"
export LOGFLUX_FAILSAFE_MODE="true"

From Environment

1
2
3
4
5
6


// Create client from environment variables
client, err := client.NewClientFromEnv("my-app", "your-secret-key")
if err != nil {
    log.Fatal(err)
}
defer client.Close()

Log Levels

Level	Value	Method	Description
Emergency	1	`.Emergency()`	System is unusable
Alert	2	`.Alert()`	Action must be taken immediately
Critical	3	`.Critical()`	Critical conditions
Error	4	`.Error()`	Error conditions
Warning	5	`.Warning()`	Warning conditions
Notice	6	`.Notice()`	Normal but significant
Info	7	`.Info()`	Informational messages
Debug	8	`.Debug()`	Debug-level messages

Logger Adapters

Standard Library Integration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import (
    "log"
    "github.com/logflux-io/logflux-go-sdk/pkg/adapters"
    "github.com/logflux-io/logflux-go-sdk/pkg/client"
)

// Replace standard library logger
client, _ := client.NewResilientClientFromEnv("my-app", "secret")
adapters.ReplaceStandardLogger(client, "[APP] ")

// Now all log package calls go to LogFlux
log.Print("This goes to LogFlux")

Logrus Adapter

1
2
3
4
5
6
7


client, _ := client.NewResilientClientFromEnv("my-app", "secret")
logger := adapters.NewLogrusLogger(client)

// Use like logrus
logger.WithField("user_id", 1234).
    WithField("action", "login").
    Info("User logged in")

Zap Adapter

1
2
3
4
5
6
7
8


client, _ := client.NewResilientClientFromEnv("my-app", "secret")
logger := adapters.NewZapLogger(client)

// Structured logging
logger.Info("User logged in",
    adapters.String("user_id", "1234"),
    adapters.Int("attempts", 1),
)

Zerolog Adapter

1
2
3
4
5
6
7
8


client, _ := client.NewResilientClientFromEnv("my-app", "secret")
logger := adapters.NewZerologLogger(client)

// Fluent interface
logger.Info().
    Str("user_id", "1234").
    Str("action", "login").
    Msg("User logged in")

Best Practices

Use Resilient Client in Production

1
2
3
4
5
6
7
8
9


config := client.ResilientClientConfig{
    ServerURL: "https://<customer-id>.ingest.<region>.logflux.io",
    Node:      "production-server",
    APIKey:    "lf_your_api_key",
    Secret:    "your-encryption-secret",
    FailsafeMode: true,  // Never crash your app
    QueueSize: 1000,     // Buffer logs during network issues
}
client := client.NewResilientClient(config)

Handle Graceful Shutdown

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


func main() {
    client := client.NewResilientClient(config)
    
    // Ensure logs are flushed on shutdown
    defer func() {
        client.Flush(10 * time.Second)
        client.Close()
    }()
    
    // Your application logic...
}

Structure Your Logs

1
2
3
4
5


// Good: Structured JSON for better searchability
client.Info(`{"event": "user_login", "user_id": "12345", "success": true}`)

// Avoid: Unstructured text
client.Info("User 12345 logged in successfully")

Common Use Cases

HTTP Request Logging

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        
        client.Info(fmt.Sprintf(`{"event": "request_start", "method": "%s", "path": "%s"}`,
            r.Method, r.URL.Path))
        
        next.ServeHTTP(w, r)
        
        client.Info(fmt.Sprintf(`{"event": "request_end", "method": "%s", "path": "%s", "duration_ms": %d}`,
            r.Method, r.URL.Path, time.Since(start).Milliseconds()))
    })
}

Database Operations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


func updateUser(userID string, data UserData) error {
    start := time.Now()
    
    client.Debug(fmt.Sprintf(`{"event": "db_query_start", "table": "users", "user_id": "%s"}`, userID))
    
    err := db.UpdateUser(userID, data)
    if err != nil {
        client.Error(fmt.Sprintf(`{"event": "db_query_error", "error": "%s"}`, err.Error()))
        return err
    }
    
    client.Info(fmt.Sprintf(`{"event": "db_query_success", "duration_ms": %d}`, 
        time.Since(start).Milliseconds()))
    
    return nil
}

Requirements

Go: 1.22 or later
Dependencies: Minimal - only standard library for core functionality
Optional: logrus, zap, zerolog (for adapters)

Support

Full Documentation: GitHub Repository
Issues: GitHub Issues
Website: logflux.io