telemetryflow/telemetryflow-go-sdk repository overview

go get github.com/telemetryflow/telemetryflow-go-sdk

TELEMETRYFLOW_API_KEY_ID=tfk_your_key_id_here
TELEMETRYFLOW_API_KEY_SECRET=tfs_your_secret_here
TELEMETRYFLOW_ENDPOINT=api.telemetryflow.id:4317
TELEMETRYFLOW_SERVICE_NAME=my-go-service
TELEMETRYFLOW_SERVICE_VERSION=1.1.1
TELEMETRYFLOW_SERVICE_NAMESPACE=telemetryflow
TELEMETRYFLOW_COLLECTOR_ID=my-collector-id
ENV=production

package main

import (
    "context"
    "log"

    "github.com/telemetryflow/telemetryflow-go-sdk/pkg/telemetryflow"
)

func main() {
    // Create client from environment variables
    client, err := telemetryflow.NewFromEnv()
    if err != nil {
        log.Fatal(err)
    }

    // Initialize the SDK
    ctx := context.Background()
    if err := client.Initialize(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Shutdown(ctx)

    // Your application code...
}

// Send a metric
client.IncrementCounter(ctx, "api.requests", 1, map[string]interface{}{
    "method": "GET",
    "status": 200,
})

// Send a log
client.LogInfo(ctx, "User logged in", map[string]interface{}{
    "user_id": "12345",
})

// Create a trace span
spanID, _ := client.StartSpan(ctx, "process-order", "internal", map[string]interface{}{
    "order_id": "67890",
})
defer client.EndSpan(ctx, spanID, nil)

pkg/telemetryflow/
├── domain/          # Domain layer (entities, value objects)
│   ├── credentials.go
│   └── config.go
├── application/     # Application layer (use cases, CQRS)
│   ├── commands.go
│   └── queries.go
├── infrastructure/  # Infrastructure layer (OTLP exporters)
│   ├── exporters.go
│   └── handlers.go
└── client.go        # Public API (interface layer)

client := telemetryflow.NewBuilder().
    WithAPIKey("tfk_...", "tfs_...").
    WithEndpoint("api.telemetryflow.id:4317").
    WithService("my-service", "1.0.0").
    WithEnvironment("production").
    WithGRPC().
    WithSignals(true, true, true). // metrics, logs, traces
    WithCustomAttribute("team", "backend").
    MustBuild()

// Counter
client.IncrementCounter(ctx, "requests.total", 1, map[string]interface{}{
    "method": "POST",
    "endpoint": "/api/users",
})

// Gauge
client.RecordGauge(ctx, "memory.usage", 512.0, map[string]interface{}{
    "unit": "MB",
})

// Histogram
client.RecordHistogram(ctx, "request.duration", 0.25, "s", map[string]interface{}{
    "endpoint": "/api/orders",
})

// Info level
client.LogInfo(ctx, "Application started", map[string]interface{}{
    "version": "1.0.0",
    "port": 8080,
})

// Warning level
client.LogWarn(ctx, "High memory usage", map[string]interface{}{
    "usage_mb": 512,
    "threshold_mb": 400,
})

// Error level
client.LogError(ctx, "Database connection failed", map[string]interface{}{
    "error": "timeout",
    "host": "db.example.com",
})

// Start a span
spanID, err := client.StartSpan(ctx, "process-payment", "internal", map[string]interface{}{
    "payment_method": "credit_card",
    "amount": 99.99,
})

// Add events to span
client.AddSpanEvent(ctx, spanID, "validation.complete", map[string]interface{}{
    "valid": true,
})

// End span (with optional error)
client.EndSpan(ctx, spanID, nil)

# Install
go install github.com/telemetryflow/telemetryflow-go-sdk/cmd/generator@latest

# Initialize integration
telemetryflow-gen init \
    --project "my-app" \
    --service "my-service" \
    --key-id "tfk_..." \
    --key-secret "tfs_..."

# Generate examples
telemetryflow-gen example http-server
telemetryflow-gen example worker

# Install
go install github.com/telemetryflow/telemetryflow-go-sdk/cmd/generator-restfulapi@latest

# Create new project
telemetryflow-restapi new \
    --name order-service \
    --module github.com/myorg/order-service \
    --db-driver postgres

# Add entities
telemetryflow-restapi entity \
    --name Order \
    --fields 'customer_id:uuid,total:decimal,status:string'

# Run SDK generator
docker run --rm -v $(pwd):/workspace telemetryflow/telemetryflow-sdk:latest \
    init --project myapp --output /workspace

# Run RESTful API generator
docker run --rm -v $(pwd):/workspace telemetryflow/telemetryflow-sdk:latest \
    telemetryflow-restapi new --name myapi --output /workspace

# Start development environment
docker-compose up -d

# Start with observability tools (Jaeger, Prometheus, Grafana)
docker-compose --profile full up -d

# Run E2E tests
docker-compose -f docker-compose.e2e.yml up --abort-on-container-exit

your-project/
├── telemetry/
│   ├── init.go           # SDK initialization
│   ├── metrics/
│   │   └── metrics.go    # Metrics helpers
│   ├── logs/
│   │   └── logs.go       # Logging helpers
│   ├── traces/
│   │   └── traces.go     # Tracing helpers
│   └── README.md
├── .env.telemetryflow    # Configuration template
└── example_*.go          # Generated examples

// gRPC (default, recommended)
config.WithProtocol(domain.ProtocolGRPC)

// HTTP
config.WithProtocol(domain.ProtocolHTTP)

config.WithRetry(
    true,                    // enabled
    3,                       // max retries
    5 * time.Second,        // backoff duration
)

config.WithBatchSettings(
    10 * time.Second,       // batch timeout
    512,                     // max batch size
)

// Enable specific signals only
config.WithSignals(
    true,   // metrics
    false,  // logs
    true,   // traces
)

// Or use convenience methods
config.WithMetricsOnly()
config.WithTracesOnly()

// Enabled by default, disable if not needed
client := telemetryflow.NewBuilder().
    WithAutoConfiguration().
    WithExemplars(false).  // Disable exemplars
    MustBuild()

// Set service namespace for multi-tenant environments
client := telemetryflow.NewBuilder().
    WithAutoConfiguration().
    WithServiceNamespace("my-namespace").
    MustBuild()

// Set collector ID for TelemetryFlow backend authentication
client := telemetryflow.NewBuilder().
    WithAutoConfiguration().
    WithCollectorID("my-unique-collector-id").
    MustBuild()

config.
    WithCustomAttribute("team", "backend").
    WithCustomAttribute("region", "us-east-1").
    WithCustomAttribute("datacenter", "dc1")

// ✅ Good: From environment
client, _ := telemetryflow.NewFromEnv()

// ✅ Good: From secret manager (example)
apiKey := secretManager.GetSecret("telemetryflow/api-key")
client, _ := telemetryflow.NewBuilder().
    WithAPIKey(apiKey.KeyID, apiKey.KeySecret).
    Build()

// ❌ Bad: Hardcoded
client, _ := telemetryflow.NewBuilder().
    WithAPIKey("tfk_hardcoded", "tfs_secret"). // DON'T DO THIS
    Build()

// Production (default)
config.WithInsecure(false)

// Testing only
config.WithInsecure(true)

func main() {
    client, _ := telemetryflow.NewFromEnv()
    ctx := context.Background()

    // Initialize
    if err := client.Initialize(ctx); err != nil {
        log.Fatal(err)
    }

    // Ensure graceful shutdown
    defer func() {
        shutdownCtx, cancel := context.WithTimeout(
            context.Background(),
            10*time.Second,
        )
        defer cancel()

        client.Flush(shutdownCtx)
        client.Shutdown(shutdownCtx)
    }()

    // Application code...
}

tests/
├── unit/              # Unit tests for individual components
│   ├── domain/        # Credentials, Config tests
│   ├── application/   # Command/Query tests
│   ├── infrastructure/# Template, HTTP, Database tests
│   └── client/        # Client, Builder tests
├── integration/       # Cross-layer integration tests
├── e2e/               # End-to-end pipeline tests
│   └── testdata/      # E2E test fixtures (OTEL config, nginx)
├── mocks/             # Mock implementations
└── fixtures/          # Test fixtures

# Run all tests
go test ./...

# Run unit tests only
go test ./tests/unit/...

# Run with verbose output
go test -v ./...

# Run with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run short tests (skip integration)
go test -short ./...

# Run e2e tests (requires environment setup)
TELEMETRYFLOW_E2E=true go test ./tests/e2e/...