{"id":28705065,"url":"https://github.com/sky93/trace-sight","last_synced_at":"2025-09-10T20:47:19.067Z","repository":{"id":298474902,"uuid":"999149742","full_name":"sky93/trace-sight","owner":"sky93","description":"A Go library that provides a pluggable interface for distributed tracing.","archived":false,"fork":false,"pushed_at":"2025-06-10T11:18:01.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-11T09:59:01.699Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sky93.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-09T20:15:41.000Z","updated_at":"2025-06-09T20:24:42.000Z","dependencies_parsed_at":"2025-06-11T09:59:06.467Z","dependency_job_id":"9796cd31-4490-4473-8cda-7108da6b470d","html_url":"https://github.com/sky93/trace-sight","commit_stats":null,"previous_names":["sky93/trace-sight"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sky93/trace-sight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ftrace-sight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ftrace-sight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ftrace-sight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ftrace-sight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sky93","download_url":"https://codeload.github.com/sky93/trace-sight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sky93%2Ftrace-sight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274526295,"owners_count":25302302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-06-14T14:09:59.590Z","updated_at":"2025-09-10T20:47:19.006Z","avatar_url":"https://github.com/sky93.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TraceSight\n\n**TraceSight** is a Go library that provides a pluggable interface for distributed tracing. Currently, it supports [Sentry](https://github.com/getsentry/sentry-go) as its first-class tracing driver, and it can be easily extended to support other tracing backends.\n\n- **Central** entrypoint: [`traceSight.go`](traceSight.go)\n- **Driver interface** definition: [`internal/drivers/drivers.go`](internal/drivers/drivers.go)\n- **Sentry driver** implementation:\n    - [`internal/drivers/sentry/tracer.go`](internal/drivers/sentry/tracer.go)\n    - [`internal/drivers/sentry/transaction.go`](internal/drivers/sentry/transaction.go)\n    - [`internal/drivers/sentry/span.go`](internal/drivers/sentry/span.go)\n\nThe library also includes an **integration** with the [Fiber](https://github.com/gofiber/fiber) framework:\n\n- **Fiber integration**: [`integrations/fiberIntegration/fiber.go`](integrations/fiberIntegration/fiber.go)\n\nBelow you will find:\n\n1. [Features](#features)\n2. [Installation](#installation)\n3. [Usage](#usage)\n4. [Fiber Integration Example](#fiber-integration-example)\n5. [Advanced Usage](#advanced-usage)\n6. [Extending TraceSight](#extending-tracesight)\n7. [Project Structure](#project-structure)\n\n---\n\n## Features\n\n- **Driver-based architecture**: Easily switch or add new backends (Sentry, etc.).\n- **Transaction \u0026 Span abstraction**: Create hierarchical traces (root transaction → child spans).\n- **Context propagation**: Transactions and spans are tied to Go's `context.Context`.\n- **User info \u0026 HTTP request binding**: Attach user data and request/response details to the trace.\n- **Fiber middleware**: Simple drop-in middleware for automatic transaction creation on each request.\n\n---\n\n## Installation\n\n```bash\ngo get github.com/sky93/trace-sight\n```\n\nTraceSight depends on [Sentry Go SDK](https://github.com/getsentry/sentry-go) and optionally [Fiber](https://github.com/gofiber/fiber). Make sure they are included in your `go.mod`.\n\n---\n\n## Usage\n\n### 1. Initialize Sentry (if you are using the Sentry driver)\n\nIn order to use the Sentry driver, ensure that Sentry is properly initialized:\n\n```go\nimport (\n    \"github.com/getsentry/sentry-go\"\n)\n\nfunc main() {\n    err := sentry.Init(sentry.ClientOptions{\n        Dsn:              \"YOUR_SENTRY_DSN\", // put your DSN here\n        EnableTracing:    true,\n        TracesSampleRate: 0.1,\n    })\n    if err != nil {\n        panic(err)\n    }\n\n    // ...\n}\n```\n\n### 2. Initialize TraceSight\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"context\"\n\n    \"github.com/sky93/trace-sight\"\n)\n\nfunc main() {\n    // 1) Initialize Sentry as above.\n    // 2) Then initialize TraceSight with the Sentry driver:\n    err := trace.New(trace.SentryDriver)\n    if err != nil {\n        panic(fmt.Errorf(\"failed to initialize TraceSight: %w\", err))\n    }\n\n    // Now you can create transactions/spans or use the Fiber middleware integration.\n    // ...\n}\n```\n\n### 3. Creating a Transaction and Span Manually\n\n```go\n// Create a root transaction\ntx, err := trace.NewTransaction(context.Background(), \"my-operation\", \"my-description\")\nif err != nil {\n    // handle error\n}\n\n// Do some work ...\n// Create a child span\nchildSpan := trace.NewSpan(tx.Context(), \"child-operation\", \"child-description\")\n// Do child work ...\nchildSpan.End()\n\n// End the root transaction\ntx.End()\n```\n\n---\n\n## Fiber Integration Example\n\nTraceSight provides a middleware for [Fiber](https://github.com/gofiber/fiber). This middleware:\n\n- Creates a new transaction for each incoming HTTP request.\n- Attaches the transaction to the request context.\n- Ends the transaction automatically after the request completes.\n\nYou can find the middleware in [`integrations/fiberIntegration/fiber.go`](integrations/fiberIntegration/fiber.go).\n\n### Setting it up\n\n```go\nimport (\n    \"log\"\n\n    \"github.com/gofiber/fiber/v2\"\n    \"github.com/sky93/trace-sight\"\n    \"github.com/sky93/trace-sight/integrations/fiberIntegration\"\n    \"github.com/getsentry/sentry-go\"\n)\n\nfunc main() {\n    // 1) Initialize Sentry\n    err := sentry.Init(sentry.ClientOptions{\n        Dsn: \"YOUR_SENTRY_DSN\",\n    })\n    if err != nil {\n        log.Fatal(\"Sentry initialization failed: \", err)\n    }\n\n    // 2) Initialize TraceSight with Sentry driver\n    err = trace.New(trace.SentryDriver)\n    if err != nil {\n        log.Fatal(\"TraceSight initialization failed: \", err)\n    }\n\n    // 3) Set up Fiber\n    app := fiber.New()\n\n    // 4) Use the TraceSight middleware\n    app.Use(fiberIntegration.TraceSightMiddleware)\n\n    // 5) Add routes\n    app.Get(\"/\", func(c *fiber.Ctx) error {\n        // Retrieve the current transaction if needed\n        tx := trace.GetCurrentTransaction(c.UserContext())\n        if tx != nil {\n            tx.SetTag(\"example-tag\", \"hello-world\")\n        }\n\n        return c.SendString(\"Hello from Fiber with Sentry tracing!\")\n    })\n\n    // 6) Start server\n    log.Fatal(app.Listen(\":3000\"))\n}\n```\n\n\u003e **Note**: The middleware will create and end a new transaction for each request. If you want to create child spans inside your handler, you can use `trace.NewSpan(c.UserContext(), \"child-span-op\", \"some description\")`.\n\n---\n\n## Advanced Usage\n\n### Attaching User Information\n\nYou can attach user information to the current transaction so that Sentry can display the user data in the event/timeline:\n\n```go\npackage main\n\nimport \"github.com/sky93/trace-sight\"\n\nfunc handler(ctx context.Context) {\n    tx := trace.GetCurrentTransaction(ctx)\n    if tx != nil {\n        userInfo := trace.CreateUser(trace.UserInfo{\n            ID:       \"12345\",\n            Email:    \"user@example.com\",\n            Username: \"myusername\",\n            IP:       \"192.168.1.1\",\n            Name:     \"John Doe\",\n        })\n        tx.SetUser(userInfo)\n    }\n    // ...\n}\n```\n\n### Setting HTTP Request or Response Details\n\nWhen using the Fiber middleware, the HTTP request is automatically attached to the transaction. You can also set the response code on the transaction if you want to override or finalize it manually:\n\n```go\ntx := trace.GetCurrentTransaction(ctx)\nif tx != nil {\n    // Once you know your response code:\n    tx.SetResponseCode(200)\n}\n```\n\n### Creating Child Spans\n\n```go\nfunc doSubOperation(ctx context.Context) {\n    childSpan := trace.NewSpan(ctx, \"sub-operation\", \"Additional details\")\n    defer childSpan.End()\n\n    // Perform sub-operation...\n\t// Use childSpan.Context() instead of ctx from now on...\n}\n```\n\n---\n\n## Extending TraceSight\n\nIf you want to add support for another tracing backend (e.g., Jaeger, Zipkin, etc.):\n\n1. Create a new driver implementing the [`drivers.TraceSight`](internal/drivers/drivers.go) interface.\n2. Provide concrete types implementing `Transaction` and `Span`.\n3. Update [`traceSight.go`](traceSight.go) to register and initialize your new driver.\n\nTraceSight is designed to be driver-agnostic, so adding new backends should be straightforward.\n\n---\n\n## Project Structure\n\n```\ntracesight/\n├── go.mod\n├── go.sum\n├── integrations\n│   └── fiberIntegration\n│       └── fiber.go              // Fiber middleware\n├── internal\n│   └── drivers\n│       ├── drivers.go           // Driver interfaces\n│       └── sentry               // Sentry driver implementation\n│           ├── span.go\n│           ├── tracer.go\n│           └── transaction.go\n└── traceSight.go                 // Main entry point and orchestrator\n```\n\n- **`traceSight.go`**: Exports the `New`, `NewTransaction`, `NewSpan`, and helper functions to interact with the chosen driver.\n- **`internal/drivers/drivers.go`**: Defines the `TraceSight`, `Transaction`, and `Span` interfaces that each driver must implement.\n- **`internal/drivers/sentry`**: Contains the Sentry-based implementation.\n- **`integrations/fiberIntegration/fiber.go`**: A sample middleware for Fiber that starts and stops transactions automatically.\n\n---\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome! Feel free to open an issue or submit a pull request.\n\n---\n\n**Enjoy tracing with TraceSight!** If you have any questions or issues, please file an issue or reach out @sky93. Contributions are always welcome.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky93%2Ftrace-sight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsky93%2Ftrace-sight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsky93%2Ftrace-sight/lists"}