Go SDK

The Astralog Go SDK is ideal for high-performance microservices and workers. It handles asynchronous batching and provides a thread-safe client for concurrent environments.

The SDK supports both Astralog Cloud and self-hosted deployments using the same ingestion API.

Installation

go get github.com/astraloghq/sdk-go

Usage

Cloud Usage

By default, the SDK sends logs to Astralog Cloud.

func main() {
    client, err := astralog.NewClient(astralog.Config{
        AuthToken: "sk_live_xxx",
        ProjectID: "my-startup",
        Service:   "worker-process",
    })
    if err != nil {
        panic(err)
    }

    defer client.Close()

    client.Info("Worker started", map[string]interface{}{
        "worker_id": 42,
        "region":    "eu-west-1",
    })
}

Self-hosted / Local Usage

Use a custom Endpoint to send logs to a local or self-hosted Astralog deployment.

func main() {
    client, err := astralog.NewClient(astralog.Config{
        Endpoint:  "http://localhost:8080/v1/drain",
        AuthToken: "default-secret-token",
        ProjectID: "my-startup",
        Service:   "worker-process",
    })
    if err != nil {
        panic(err)
    }

    defer client.Close()

    client.Info("Worker started", map[string]interface{}{
        "worker_id": 42,
        "region":    "eu-west-1",
    })
}

Configuration

The SDK is configured using astralog.Config.

Field	Type	Required	Description
`AuthToken`	`string`	Yes	Authentication token used to authorize ingestion requests.
`ProjectID`	`string`	Yes	Unique identifier for your organization or project.
`Service`	`string`	Yes	Name of the service, worker or process generating logs.
`Endpoint`	`string`	No	Custom ingestion endpoint. If omitted, Astralog Cloud is used automatically.
`MaxBatchSize`	`int`	No	Maximum number of logs buffered before automatic flush. Default: `100`.
`FlushInterval`	`time.Duration`	No	Maximum time logs stay buffered before automatic flush. Default: `5s`.
`HTTPClient`	`*http.Client`	No	Custom HTTP client for advanced networking or transport configuration.

Log Levels

The SDK provides helper methods for common log levels.

Info

client.Info("Worker started", nil)

Error

client.Error("Database connection failed", map[string]interface{}{
    "database": "postgres",
})

Debug

client.Debug("Cache miss", map[string]interface{}{
    "key": "session_123",
})

Warn

client.Warn("Retrying request", map[string]interface{}{
    "attempt": 2,
})

Metadata

Metadata allows attaching structured context to logs.

client.Info("User logged in", map[string]interface{}{
    "user_id": 123,
    "ip":      "1.1.1.1",
    "region":  "eu-west-1",
})

Metadata is optional and may contain any JSON-compatible values.

Automatic Batching

The SDK batches logs asynchronously to reduce network overhead and improve throughput.

Logs are automatically flushed when:

MaxBatchSize is reached
FlushInterval expires
client.Close() is called

No manual buffering is required.

Graceful Shutdown

Always call Close() before application shutdown.

This guarantees remaining buffered logs are flushed before exit.

defer client.Close()

Advanced Configuration

Customize batching and transport behavior.

client, err := astralog.NewClient(astralog.Config{
    AuthToken:     "sk_live_xxx",
    ProjectID:     "my-startup",
    Service:       "worker-process",
    MaxBatchSize:  500,
    FlushInterval: 2 * time.Second,
})

Custom HTTP client:

client, err := astralog.NewClient(astralog.Config{
    AuthToken: "sk_live_xxx",
    HTTPClient: &http.Client{
        Timeout: 30 * time.Second,
    },
})