https://github.com/sky93/trace-sight
A Go library that provides a pluggable interface for distributed tracing.
https://github.com/sky93/trace-sight
Last synced: 10 months ago
JSON representation
A Go library that provides a pluggable interface for distributed tracing.
- Host: GitHub
- URL: https://github.com/sky93/trace-sight
- Owner: sky93
- License: mit
- Created: 2025-06-09T20:15:41.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-10T11:18:01.000Z (about 1 year ago)
- Last Synced: 2025-06-11T09:59:01.699Z (about 1 year ago)
- Language: Go
- Size: 11.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TraceSight
**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.
- **Central** entrypoint: [`traceSight.go`](traceSight.go)
- **Driver interface** definition: [`internal/drivers/drivers.go`](internal/drivers/drivers.go)
- **Sentry driver** implementation:
- [`internal/drivers/sentry/tracer.go`](internal/drivers/sentry/tracer.go)
- [`internal/drivers/sentry/transaction.go`](internal/drivers/sentry/transaction.go)
- [`internal/drivers/sentry/span.go`](internal/drivers/sentry/span.go)
The library also includes an **integration** with the [Fiber](https://github.com/gofiber/fiber) framework:
- **Fiber integration**: [`integrations/fiberIntegration/fiber.go`](integrations/fiberIntegration/fiber.go)
Below you will find:
1. [Features](#features)
2. [Installation](#installation)
3. [Usage](#usage)
4. [Fiber Integration Example](#fiber-integration-example)
5. [Advanced Usage](#advanced-usage)
6. [Extending TraceSight](#extending-tracesight)
7. [Project Structure](#project-structure)
---
## Features
- **Driver-based architecture**: Easily switch or add new backends (Sentry, etc.).
- **Transaction & Span abstraction**: Create hierarchical traces (root transaction → child spans).
- **Context propagation**: Transactions and spans are tied to Go's `context.Context`.
- **User info & HTTP request binding**: Attach user data and request/response details to the trace.
- **Fiber middleware**: Simple drop-in middleware for automatic transaction creation on each request.
---
## Installation
```bash
go get github.com/sky93/trace-sight
```
TraceSight 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`.
---
## Usage
### 1. Initialize Sentry (if you are using the Sentry driver)
In order to use the Sentry driver, ensure that Sentry is properly initialized:
```go
import (
"github.com/getsentry/sentry-go"
)
func main() {
err := sentry.Init(sentry.ClientOptions{
Dsn: "YOUR_SENTRY_DSN", // put your DSN here
EnableTracing: true,
TracesSampleRate: 0.1,
})
if err != nil {
panic(err)
}
// ...
}
```
### 2. Initialize TraceSight
```go
package main
import (
"fmt"
"context"
"github.com/sky93/trace-sight"
)
func main() {
// 1) Initialize Sentry as above.
// 2) Then initialize TraceSight with the Sentry driver:
err := trace.New(trace.SentryDriver)
if err != nil {
panic(fmt.Errorf("failed to initialize TraceSight: %w", err))
}
// Now you can create transactions/spans or use the Fiber middleware integration.
// ...
}
```
### 3. Creating a Transaction and Span Manually
```go
// Create a root transaction
tx, err := trace.NewTransaction(context.Background(), "my-operation", "my-description")
if err != nil {
// handle error
}
// Do some work ...
// Create a child span
childSpan := trace.NewSpan(tx.Context(), "child-operation", "child-description")
// Do child work ...
childSpan.End()
// End the root transaction
tx.End()
```
---
## Fiber Integration Example
TraceSight provides a middleware for [Fiber](https://github.com/gofiber/fiber). This middleware:
- Creates a new transaction for each incoming HTTP request.
- Attaches the transaction to the request context.
- Ends the transaction automatically after the request completes.
You can find the middleware in [`integrations/fiberIntegration/fiber.go`](integrations/fiberIntegration/fiber.go).
### Setting it up
```go
import (
"log"
"github.com/gofiber/fiber/v2"
"github.com/sky93/trace-sight"
"github.com/sky93/trace-sight/integrations/fiberIntegration"
"github.com/getsentry/sentry-go"
)
func main() {
// 1) Initialize Sentry
err := sentry.Init(sentry.ClientOptions{
Dsn: "YOUR_SENTRY_DSN",
})
if err != nil {
log.Fatal("Sentry initialization failed: ", err)
}
// 2) Initialize TraceSight with Sentry driver
err = trace.New(trace.SentryDriver)
if err != nil {
log.Fatal("TraceSight initialization failed: ", err)
}
// 3) Set up Fiber
app := fiber.New()
// 4) Use the TraceSight middleware
app.Use(fiberIntegration.TraceSightMiddleware)
// 5) Add routes
app.Get("/", func(c *fiber.Ctx) error {
// Retrieve the current transaction if needed
tx := trace.GetCurrentTransaction(c.UserContext())
if tx != nil {
tx.SetTag("example-tag", "hello-world")
}
return c.SendString("Hello from Fiber with Sentry tracing!")
})
// 6) Start server
log.Fatal(app.Listen(":3000"))
}
```
> **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")`.
---
## Advanced Usage
### Attaching User Information
You can attach user information to the current transaction so that Sentry can display the user data in the event/timeline:
```go
package main
import "github.com/sky93/trace-sight"
func handler(ctx context.Context) {
tx := trace.GetCurrentTransaction(ctx)
if tx != nil {
userInfo := trace.CreateUser(trace.UserInfo{
ID: "12345",
Email: "user@example.com",
Username: "myusername",
IP: "192.168.1.1",
Name: "John Doe",
})
tx.SetUser(userInfo)
}
// ...
}
```
### Setting HTTP Request or Response Details
When 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:
```go
tx := trace.GetCurrentTransaction(ctx)
if tx != nil {
// Once you know your response code:
tx.SetResponseCode(200)
}
```
### Creating Child Spans
```go
func doSubOperation(ctx context.Context) {
childSpan := trace.NewSpan(ctx, "sub-operation", "Additional details")
defer childSpan.End()
// Perform sub-operation...
// Use childSpan.Context() instead of ctx from now on...
}
```
---
## Extending TraceSight
If you want to add support for another tracing backend (e.g., Jaeger, Zipkin, etc.):
1. Create a new driver implementing the [`drivers.TraceSight`](internal/drivers/drivers.go) interface.
2. Provide concrete types implementing `Transaction` and `Span`.
3. Update [`traceSight.go`](traceSight.go) to register and initialize your new driver.
TraceSight is designed to be driver-agnostic, so adding new backends should be straightforward.
---
## Project Structure
```
tracesight/
├── go.mod
├── go.sum
├── integrations
│ └── fiberIntegration
│ └── fiber.go // Fiber middleware
├── internal
│ └── drivers
│ ├── drivers.go // Driver interfaces
│ └── sentry // Sentry driver implementation
│ ├── span.go
│ ├── tracer.go
│ └── transaction.go
└── traceSight.go // Main entry point and orchestrator
```
- **`traceSight.go`**: Exports the `New`, `NewTransaction`, `NewSpan`, and helper functions to interact with the chosen driver.
- **`internal/drivers/drivers.go`**: Defines the `TraceSight`, `Transaction`, and `Span` interfaces that each driver must implement.
- **`internal/drivers/sentry`**: Contains the Sentry-based implementation.
- **`integrations/fiberIntegration/fiber.go`**: A sample middleware for Fiber that starts and stops transactions automatically.
---
## Contributing
Contributions, bug reports, and feature requests are welcome! Feel free to open an issue or submit a pull request.
---
**Enjoy tracing with TraceSight!** If you have any questions or issues, please file an issue or reach out @sky93. Contributions are always welcome.