{"id":34741893,"url":"https://github.com/telemetryflow/telemetryflow-go-sdk","last_synced_at":"2026-04-17T19:04:29.391Z","repository":{"id":330076650,"uuid":"1121477497","full_name":"telemetryflow/telemetryflow-go-sdk","owner":"telemetryflow","description":"Enterprise-grade Go SDK for TelemetryFlow - the observability platform that provides unified metrics, logs, and traces collection following OpenTelemetry standards.","archived":false,"fork":false,"pushed_at":"2026-01-01T09:36:33.000Z","size":391,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-02T12:37:25.122Z","etag":null,"topics":["devopscorner","observability","opentelemetry","opentelemetry-go","opentelemetry-sdk","otel","telemetryflow"],"latest_commit_sha":null,"homepage":"https://www.telemetryflow.id","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telemetryflow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T04:06:16.000Z","updated_at":"2026-01-01T09:36:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/telemetryflow/telemetryflow-go-sdk","commit_stats":null,"previous_names":["telemetryflow/telemetryflow-go-sdk"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/telemetryflow/telemetryflow-go-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-go-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-go-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-go-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-go-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telemetryflow","download_url":"https://codeload.github.com/telemetryflow/telemetryflow-go-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telemetryflow%2Ftelemetryflow-go-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31941845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devopscorner","observability","opentelemetry","opentelemetry-go","opentelemetry-sdk","otel","telemetryflow"],"created_at":"2025-12-25T04:17:34.048Z","updated_at":"2026-04-17T19:04:29.384Z","avatar_url":"https://github.com/telemetryflow.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-sdk-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-sdk-light.svg\"\u003e\n    \u003cimg src=\"https://github.com/telemetryflow/.github/raw/main/docs/assets/tfo-logo-sdk-light.svg\" alt=\"TelemetryFlow Logo\" width=\"80%\"\u003e\n  \u003c/picture\u003e\n\n  \u003ch3\u003eTelemetryFlow GO SDK\u003c/h3\u003e\n\n[![Version](https://img.shields.io/badge/Version-1.1.2-orange.svg)](CHANGELOG.md)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go)](https://golang.org/)\n[![OTEL SDK](https://img.shields.io/badge/OpenTelemetry_SDK-1.39.0-blueviolet)](https://opentelemetry.io/)\n[![OpenTelemetry](https://img.shields.io/badge/OTLP-100%25%20Compliant-success?logo=opentelemetry)](https://opentelemetry.io/)\n[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat\u0026logo=docker)](https://hub.docker.com/r/telemetryflow/telemetryflow-sdk)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  Enterprise-grade Go SDK for \u003ca href=\"https://telemetryflow.id\"\u003eTelemetryFlow\u003c/a\u003e - the observability platform that provides unified metrics, logs, and traces collection following OpenTelemetry standards.\n\u003c/p\u003e\n\n---\n\n## 🌟 Features\n\n- **100% OTLP Compliant**: Full OpenTelemetry Protocol implementation\n- **DDD Architecture**: Domain-Driven Design with clear bounded contexts\n- **CQRS Pattern**: Separate command and query responsibilities\n- **Easy Integration**: Builder pattern and environment-based configuration\n- **Exemplars Support**: Metrics-to-traces correlation for powerful debugging\n- **Service Graph Ready**: Compatible with OTEL Collector servicegraph connector\n- **Enhanced gRPC Settings**: Configurable keepalive, buffer sizes, and message limits\n- **TelemetryFlow Headers**: Custom headers for collector authentication\n- **Code Generators**: CLI tools for quick project setup\n  - `telemetryflow-gen`: SDK integration generator\n  - `telemetryflow-restapi`: DDD + CQRS RESTful API generator\n- **Docker Ready**: Multi-stage Dockerfile and Docker Compose configurations\n- **Production Ready**: Comprehensive error handling, retries, and batching\n- **Type Safe**: Strong typing with compile-time safety\n- **Zero Dependencies** (core): Minimal external dependencies in core SDK\n- **E2E Testing**: Complete end-to-end testing infrastructure\n- **Extensible**: Easy to extend for custom use cases\n\n## 📦 Installation\n\n```bash\ngo get github.com/telemetryflow/telemetryflow-go-sdk\n```\n\n## 🚀 Quick Start\n\n### 1. Environment Variables Setup\n\nCreate a `.env` file:\n\n```bash\nTELEMETRYFLOW_API_KEY_ID=tfk_your_key_id_here\nTELEMETRYFLOW_API_KEY_SECRET=tfs_your_secret_here\nTELEMETRYFLOW_ENDPOINT=api.telemetryflow.id:4317\nTELEMETRYFLOW_SERVICE_NAME=my-go-service\nTELEMETRYFLOW_SERVICE_VERSION=1.1.1\nTELEMETRYFLOW_SERVICE_NAMESPACE=telemetryflow\nTELEMETRYFLOW_COLLECTOR_ID=my-collector-id\nENV=production\n```\n\n### 2. Initialize SDK\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n\n    \"github.com/telemetryflow/telemetryflow-go-sdk/pkg/telemetryflow\"\n)\n\nfunc main() {\n    // Create client from environment variables\n    client, err := telemetryflow.NewFromEnv()\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // Initialize the SDK\n    ctx := context.Background()\n    if err := client.Initialize(ctx); err != nil {\n        log.Fatal(err)\n    }\n    defer client.Shutdown(ctx)\n\n    // Your application code...\n}\n```\n\n### 3. Send Telemetry\n\n```go\n// Send a metric\nclient.IncrementCounter(ctx, \"api.requests\", 1, map[string]interface{}{\n    \"method\": \"GET\",\n    \"status\": 200,\n})\n\n// Send a log\nclient.LogInfo(ctx, \"User logged in\", map[string]interface{}{\n    \"user_id\": \"12345\",\n})\n\n// Create a trace span\nspanID, _ := client.StartSpan(ctx, \"process-order\", \"internal\", map[string]interface{}{\n    \"order_id\": \"67890\",\n})\ndefer client.EndSpan(ctx, spanID, nil)\n```\n\n## 🏗️ Architecture\n\nThe SDK follows Domain-Driven Design (DDD) and CQRS patterns:\n\n```\npkg/telemetryflow/\n├── domain/          # Domain layer (entities, value objects)\n│   ├── credentials.go\n│   └── config.go\n├── application/     # Application layer (use cases, CQRS)\n│   ├── commands.go\n│   └── queries.go\n├── infrastructure/  # Infrastructure layer (OTLP exporters)\n│   ├── exporters.go\n│   └── handlers.go\n└── client.go        # Public API (interface layer)\n```\n\n### Domain Layer\n\nCore business entities and value objects:\n- `Credentials`: Immutable API key pair with validation\n- `TelemetryConfig`: Aggregate root containing all configuration\n\n### Application Layer\n\nCQRS implementation:\n- **Commands**: `RecordMetricCommand`, `EmitLogCommand`, `StartSpanCommand`, etc.\n- **Queries**: `GetMetricQuery`, `GetLogsQuery`, `GetTraceQuery`, etc.\n- **Command/Query Buses**: Route requests to appropriate handlers\n\n### Infrastructure Layer\n\nTechnical implementations:\n- `OTLPExporterFactory`: Creates OTLP exporters (gRPC/HTTP)\n- `TelemetryCommandHandler`: Handles telemetry commands\n- OpenTelemetry SDK integration\n\n## 📚 Usage Examples\n\n### Builder Pattern\n\n```go\nclient := telemetryflow.NewBuilder().\n    WithAPIKey(\"tfk_...\", \"tfs_...\").\n    WithEndpoint(\"api.telemetryflow.id:4317\").\n    WithService(\"my-service\", \"1.0.0\").\n    WithEnvironment(\"production\").\n    WithGRPC().\n    WithSignals(true, true, true). // metrics, logs, traces\n    WithCustomAttribute(\"team\", \"backend\").\n    MustBuild()\n```\n\n### Metrics\n\n```go\n// Counter\nclient.IncrementCounter(ctx, \"requests.total\", 1, map[string]interface{}{\n    \"method\": \"POST\",\n    \"endpoint\": \"/api/users\",\n})\n\n// Gauge\nclient.RecordGauge(ctx, \"memory.usage\", 512.0, map[string]interface{}{\n    \"unit\": \"MB\",\n})\n\n// Histogram\nclient.RecordHistogram(ctx, \"request.duration\", 0.25, \"s\", map[string]interface{}{\n    \"endpoint\": \"/api/orders\",\n})\n```\n\n### Logs\n\n```go\n// Info level\nclient.LogInfo(ctx, \"Application started\", map[string]interface{}{\n    \"version\": \"1.0.0\",\n    \"port\": 8080,\n})\n\n// Warning level\nclient.LogWarn(ctx, \"High memory usage\", map[string]interface{}{\n    \"usage_mb\": 512,\n    \"threshold_mb\": 400,\n})\n\n// Error level\nclient.LogError(ctx, \"Database connection failed\", map[string]interface{}{\n    \"error\": \"timeout\",\n    \"host\": \"db.example.com\",\n})\n```\n\n### Traces\n\n```go\n// Start a span\nspanID, err := client.StartSpan(ctx, \"process-payment\", \"internal\", map[string]interface{}{\n    \"payment_method\": \"credit_card\",\n    \"amount\": 99.99,\n})\n\n// Add events to span\nclient.AddSpanEvent(ctx, spanID, \"validation.complete\", map[string]interface{}{\n    \"valid\": true,\n})\n\n// End span (with optional error)\nclient.EndSpan(ctx, spanID, nil)\n```\n\n## 🛠️ Code Generators\n\nThe SDK includes powerful code generators to bootstrap your integration.\n\n### SDK Generator (`telemetryflow-gen`)\n\nGenerates TelemetryFlow SDK integration code for existing projects.\n\n```bash\n# Install\ngo install github.com/telemetryflow/telemetryflow-go-sdk/cmd/generator@latest\n\n# Initialize integration\ntelemetryflow-gen init \\\n    --project \"my-app\" \\\n    --service \"my-service\" \\\n    --key-id \"tfk_...\" \\\n    --key-secret \"tfs_...\"\n\n# Generate examples\ntelemetryflow-gen example http-server\ntelemetryflow-gen example worker\n```\n\n### RESTful API Generator (`telemetryflow-restapi`)\n\nGenerates complete DDD + CQRS RESTful API projects with Echo framework.\n\n```bash\n# Install\ngo install github.com/telemetryflow/telemetryflow-go-sdk/cmd/generator-restfulapi@latest\n\n# Create new project\ntelemetryflow-restapi new \\\n    --name order-service \\\n    --module github.com/myorg/order-service \\\n    --db-driver postgres\n\n# Add entities\ntelemetryflow-restapi entity \\\n    --name Order \\\n    --fields 'customer_id:uuid,total:decimal,status:string'\n```\n\nSee [Generator Documentation](docs/GENERATOR.md) and [RESTful API Generator](docs/GENERATOR_RESTAPI.md) for details.\n\n## 🐳 Docker\n\n### Using Docker\n\n```bash\n# Run SDK generator\ndocker run --rm -v $(pwd):/workspace telemetryflow/telemetryflow-sdk:latest \\\n    init --project myapp --output /workspace\n\n# Run RESTful API generator\ndocker run --rm -v $(pwd):/workspace telemetryflow/telemetryflow-sdk:latest \\\n    telemetryflow-restapi new --name myapi --output /workspace\n```\n\n### Docker Compose\n\nDevelopment environment with full observability stack:\n\n```bash\n# Start development environment\ndocker-compose up -d\n\n# Start with observability tools (Jaeger, Prometheus, Grafana)\ndocker-compose --profile full up -d\n\n# Run E2E tests\ndocker-compose -f docker-compose.e2e.yml up --abort-on-container-exit\n```\n\n### Generated Structure\n\n```\nyour-project/\n├── telemetry/\n│   ├── init.go           # SDK initialization\n│   ├── metrics/\n│   │   └── metrics.go    # Metrics helpers\n│   ├── logs/\n│   │   └── logs.go       # Logging helpers\n│   ├── traces/\n│   │   └── traces.go     # Tracing helpers\n│   └── README.md\n├── .env.telemetryflow    # Configuration template\n└── example_*.go          # Generated examples\n```\n\n## 🎯 Advanced Configuration\n\n### Protocol Selection\n\n```go\n// gRPC (default, recommended)\nconfig.WithProtocol(domain.ProtocolGRPC)\n\n// HTTP\nconfig.WithProtocol(domain.ProtocolHTTP)\n```\n\n### Retry Configuration\n\n```go\nconfig.WithRetry(\n    true,                    // enabled\n    3,                       // max retries\n    5 * time.Second,        // backoff duration\n)\n```\n\n### Batch Settings\n\n```go\nconfig.WithBatchSettings(\n    10 * time.Second,       // batch timeout\n    512,                     // max batch size\n)\n```\n\n### Signal Control\n\n```go\n// Enable specific signals only\nconfig.WithSignals(\n    true,   // metrics\n    false,  // logs\n    true,   // traces\n)\n\n// Or use convenience methods\nconfig.WithMetricsOnly()\nconfig.WithTracesOnly()\n```\n\n### Exemplars Support (v1.1.1+)\n\nExemplars enable metrics-to-traces correlation for powerful debugging:\n\n```go\n// Enabled by default, disable if not needed\nclient := telemetryflow.NewBuilder().\n    WithAutoConfiguration().\n    WithExemplars(false).  // Disable exemplars\n    MustBuild()\n```\n\n### Service Namespace (v1.1.1+)\n\n```go\n// Set service namespace for multi-tenant environments\nclient := telemetryflow.NewBuilder().\n    WithAutoConfiguration().\n    WithServiceNamespace(\"my-namespace\").\n    MustBuild()\n```\n\n### Collector ID (v1.1.1+)\n\n```go\n// Set collector ID for TelemetryFlow backend authentication\nclient := telemetryflow.NewBuilder().\n    WithAutoConfiguration().\n    WithCollectorID(\"my-unique-collector-id\").\n    MustBuild()\n```\n\n### Custom Resource Attributes\n\n```go\nconfig.\n    WithCustomAttribute(\"team\", \"backend\").\n    WithCustomAttribute(\"region\", \"us-east-1\").\n    WithCustomAttribute(\"datacenter\", \"dc1\")\n```\n\n## 🔒 Security\n\n### API Key Management\n\nAPI keys should **never** be hardcoded. Use environment variables or secure secret management:\n\n```go\n// ✅ Good: From environment\nclient, _ := telemetryflow.NewFromEnv()\n\n// ✅ Good: From secret manager (example)\napiKey := secretManager.GetSecret(\"telemetryflow/api-key\")\nclient, _ := telemetryflow.NewBuilder().\n    WithAPIKey(apiKey.KeyID, apiKey.KeySecret).\n    Build()\n\n// ❌ Bad: Hardcoded\nclient, _ := telemetryflow.NewBuilder().\n    WithAPIKey(\"tfk_hardcoded\", \"tfs_secret\"). // DON'T DO THIS\n    Build()\n```\n\n### TLS/SSL\n\nBy default, the SDK uses secure connections. Only disable for testing:\n\n```go\n// Production (default)\nconfig.WithInsecure(false)\n\n// Testing only\nconfig.WithInsecure(true)\n```\n\n## 📊 Best Practices\n\n1. **Initialize Once**: Create one client instance per application\n2. **Defer Shutdown**: Always defer `client.Shutdown(ctx)`\n3. **Context Propagation**: Pass context through your call chain\n4. **Attribute Cardinality**: Limit high-cardinality attributes\n5. **Batch Configuration**: Tune batch settings for your workload\n6. **Error Handling**: Always check errors from telemetry calls\n7. **Graceful Shutdown**: Allow time for final flush\n\n```go\nfunc main() {\n    client, _ := telemetryflow.NewFromEnv()\n    ctx := context.Background()\n\n    // Initialize\n    if err := client.Initialize(ctx); err != nil {\n        log.Fatal(err)\n    }\n\n    // Ensure graceful shutdown\n    defer func() {\n        shutdownCtx, cancel := context.WithTimeout(\n            context.Background(),\n            10*time.Second,\n        )\n        defer cancel()\n\n        client.Flush(shutdownCtx)\n        client.Shutdown(shutdownCtx)\n    }()\n\n    // Application code...\n}\n```\n\n## 🧪 Testing\n\nThe SDK includes comprehensive tests organized by type:\n\n```text\ntests/\n├── unit/              # Unit tests for individual components\n│   ├── domain/        # Credentials, Config tests\n│   ├── application/   # Command/Query tests\n│   ├── infrastructure/# Template, HTTP, Database tests\n│   └── client/        # Client, Builder tests\n├── integration/       # Cross-layer integration tests\n├── e2e/               # End-to-end pipeline tests\n│   └── testdata/      # E2E test fixtures (OTEL config, nginx)\n├── mocks/             # Mock implementations\n└── fixtures/          # Test fixtures\n```\n\n### Running Tests\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run unit tests only\ngo test ./tests/unit/...\n\n# Run with verbose output\ngo test -v ./...\n\n# Run with coverage\ngo test -cover ./...\n\n# Generate coverage report\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n\n# Run short tests (skip integration)\ngo test -short ./...\n\n# Run e2e tests (requires environment setup)\nTELEMETRYFLOW_E2E=true go test ./tests/e2e/...\n```\n\n### Test Coverage Goals\n\n| Layer          | Target |\n| -------------- | ------ |\n| Domain         | 90%+   |\n| Application    | 85%+   |\n| Infrastructure | 80%+   |\n| Client         | 85%+   |\n\n## 📖 Documentation\n\n- [Quickstart Guide](docs/QUICKSTART.md) - Get started in 5 minutes\n- [Architecture Guide](docs/ARCHITECTURE.md) - SDK architecture with DDD/CQRS patterns\n- [API Reference](docs/API_REFERENCE.md) - Complete API documentation\n- [SDK Generator](docs/GENERATOR.md) - telemetryflow-gen CLI documentation\n- [RESTful API Generator](docs/GENERATOR_RESTAPI.md) - telemetryflow-restapi CLI documentation\n- [Examples](examples/) - Sample applications and patterns\n- [Changelog](CHANGELOG.md) - Version history and release notes\n- [TelemetryFlow Platform](https://docs.telemetryflow.id) - Platform documentation\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🆘 Support\n\n- 📧 Email: support@telemetryflow.id\n- 💬 Slack: [TelemetryFlow Community](https://telemetryflow.slack.com)\n- 📚 Docs: [https://docs.telemetryflow.id](https://docs.telemetryflow.id)\n- 🐛 Issues: [GitHub Issues](https://github.com/telemetryflow/telemetryflow-go-sdk/issues)\n\n## 🙏 Acknowledgments\n\n- [OpenTelemetry](https://opentelemetry.io/) for the excellent instrumentation standard\n- All contributors who have helped shape this SDK\n\n---\n\nBuilt with ❤️ by the **DevOpsCorner Indonesia**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-go-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-go-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetryflow%2Ftelemetryflow-go-sdk/lists"}