README
¶
go-telemetry - OTEL HTTP Telemetry
Documentation
Official godoc documentation (with examples) can be found at the Package Registry.
Usage
Add Package Dependency
go get -u github.com/poly-gun/go-telemetry
Import and Implement
main.go
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"os"
"time"
"github.com/poly-gun/go-telemetry"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/trace"
)
// ctx, cancel represent the server's runtime context and cancellation handler.
var ctx, cancel = context.WithCancel(context.Background())
func main() {
defer cancel() // Eventually stop the open-telemetry client.
ctx, span := otel.Tracer("example").Start(ctx, "main", trace.WithSpanKind(trace.SpanKindUnspecified))
_ = ctx // Real implementation is likely to make use of the ctx.
// Typical use case of the span would be to defer span.End() after initialization; however, in the example, we need to
// control when it ends in order to capture the output and write it out as the example.
// defer span.End()
// Add an event (in many observability tools, this gets represented as a log message).
span.AddEvent("example-event-log-1", trace.WithAttributes(attribute.String("message", "Hello World")))
span.End()
time.Sleep(5 * time.Second)
// Output: A metrics and trace message(s) in JSON format, printed to standard-output.
}
func init() {
// Setup the telemetry pipeline and cancellation handler.
shutdown := telemetry.Setup(ctx, func(o *telemetry.Settings) {
if os.Getenv("CI") == "" { // Example of running the program in a local, development environment.
o.Zipkin.Enabled = false
o.Tracer.Local = true
o.Tracer.Options = nil
o.Tracer.Writer = os.Stdout
o.Metrics.Local = true
o.Metrics.Options = nil
o.Metrics.Writer = os.Stdout
o.Logs.Local = true
o.Logs.Options = nil
o.Logs.Writer = os.Stdout
} else {
o.Zipkin.URL = "http://zipkin.istio-system.svc.cluster.local:9411"
}
})
// Initialize the telemetry interrupt handler.
telemetry.Interrupt(ctx, cancel, shutdown)
}
- Please refer to the code examples for additional usage and implementation details.
- See https://pkgo.dev/github.com/poly-gun/go-telemetry for additional documentation.
Contributions
See the Contributing Guide for additional details on getting started.
Task-Board
- Create a Resource Detector for Kubernetes Telemetry.
Documentation
¶
Overview ¶
Example ¶
package main
import (
"context"
"os"
"time"
"github.com/poly-gun/go-telemetry"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/trace"
)
// ctx, cancel represent the server's runtime context and cancellation handler.
var ctx, cancel = context.WithCancel(context.Background())
func main() {
defer cancel() // Eventually stop the open-telemetry client.
ctx, span := otel.Tracer("example").Start(ctx, "main", trace.WithSpanKind(trace.SpanKindUnspecified))
_ = ctx // Real implementation is likely to make use of the ctx.
// Typical use case of the span would be to defer span.End() after initialization; however, in the example, we need to
// control when it ends in order to capture the output and write it out as the example.
// defer span.End()
// Add an event (in many observability tools, this gets represented as a log message).
span.AddEvent("example-event-log-1", trace.WithAttributes(attribute.String("message", "Hello World")))
span.End()
time.Sleep(5 * time.Second)
// The output will include metrics and trace message(s) in JSON format, printed to standard-output.
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Interrupt ¶
func Interrupt(ctx context.Context, cancel context.CancelFunc, shutdown func(context.Context) error) chan os.Signal
Interrupt is a graceful interrupt + signal handler for the telemetry pipeline.
Example ¶
const service = "example-service"
const version = "0.0.0"
_ = os.Setenv("OTEL_RESOURCE_ATTRIBUTES", fmt.Sprintf("service.name=%s,service.version=%s", service, version))
ctx, cancel := context.WithCancel(context.Background())
// Telemetry Setup + Cancellation Handler
shutdown := telemetry.Setup(ctx, func(options *telemetry.Settings) {
options.Zipkin.Enabled = false // disabled during testing
options.Tracer.Local = true
options.Metrics.Local = true
options.Logs.Local = true
options.Metrics.Writer = io.Discard // prevent output from filling the test logs
})
listener := telemetry.Interrupt(ctx, cancel, shutdown)
time.Sleep(5 * time.Second)
listener <- syscall.SIGTERM
<-ctx.Done()
fmt.Println("Telemetry Shutdown Complete")
Output: Telemetry Shutdown Complete
Types ¶
type Logs ¶
type Logs struct {
// Logs represents [otlploghttp.Option] configurations.
//
// Defaults:
//
// - otlploghttp.WithInsecure()
// - otlploghttp.WithEndpoint("http://zipkin.istio-system.svc.cluster.local:9411")
Options []otlploghttp.Option
// Debugger configures an additional [stdoutlog.Exporter] if not nil. Defaults nil.
Debugger *stdoutlog.Exporter
// Local will prevent an external log exporter from getting used as a processor. If true, forces [Logs.Debugger] configuration. Default is false.
Local bool
// Writer is an optional [io.Writer] for usage when [Logs.Local] or [Logs.Debugger] options are configured. Defaults to [os.Stdout].
Writer io.Writer
}
type Metrics ¶
type Metrics struct {
// Options represents [otlpmetrichttp.Option] configurations.
//
// Defaults:
//
// - otlpmetrichttp.WithInsecure()
// - otlpmetrichttp.WithEndpoint("opentelemetry-collector.observability.svc.cluster.local:4318")
Options []otlpmetrichttp.Option
// Debugger configures an additional [metric.Exporter] if not nil. Defaults nil.
Debugger metric.Exporter
// Local will prevent an external metrics provider from getting used. If true, forces [Metrics.Debugger] configuration. Default is false.
Local bool
// Writer is an optional [io.Writer] for usage when [Metrics.Local] or [Metrics.Debugger] options are configured. Defaults to [os.Stdout].
Writer io.Writer
}
type Settings ¶
type Settings struct {
// Zipkin represents a zipkin collector.
Zipkin *Zipkin
// Tracer represents [otlptracehttp.Option] configurations.
Tracer *Tracer
// Metrics represents [otlpmetrichttp.Option] configurations.
Metrics *Metrics
// Logs represents [otlploghttp.Option] configurations.
Logs *Logs
// Propagators ...
//
// Defaults:
//
// - [propagation.TraceContext]
// - [propagation.Baggage]
Propagators []propagation.TextMapPropagator
}
type Tracer ¶
type Tracer struct {
// Options represents [otlptracehttp.Option] configurations.
//
// Defaults:
//
// - otlptracehttp.WithInsecure()
// - otlptracehttp.WithEndpoint("opentelemetry-collector.observability.svc.cluster.local:4318")
Options []otlptracehttp.Option
// Debugger configures an additional [stdouttrace.Exporter] if not nil. Defaults nil.
Debugger *stdouttrace.Exporter
// Local will prevent an external tracer from getting used as a provider. If true, forces [Tracer.Debugger] configuration. Default is false.
Local bool
// Writer is an optional [io.Writer] for usage when [Tracer.Local] or [Tracer.Debugger] options are configured. Defaults to [os.Stdout].
Writer io.Writer
}
Tracer represents a tracer configuration for OpenTelemetry.
type Zipkin ¶
type Zipkin struct {
// URL - Zipkin collector url - defaults to "http://opentelemetry-collector.observability.svc.cluster.local:9441".
URL string
// Enabled will enable the Zipkin collector. Default is true.
Enabled bool
}
Zipkin represents the configuration for a Zipkin collector. URL specifies the Zipkin collector URL, defaulting to "http://opentelemetry-collector.observability.svc.cluster.local:9441". Enabled determines if the Zipkin collector is active. Default is true.
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.