OpenTelemetry Beego monitoring [otelbeego]

OpenTelemetry Beego instrumentation allows developers to monitor and diagnose issues with their Beego applications, providing valuable insights into application behavior in production.

Quick Setup

Minimal working example:

import (
    "github.com/astaxie/beego"
    "go.opentelemetry.io/contrib/instrumentation/github.com/astaxie/beego/otelbeego"
)

func main() {
    mware := otelbeego.NewOTelBeegoMiddleWare("my-service")

    beego.Router("/", &MainController{})
    beego.RunWithMiddleWares(":8080", mware)
}

This single middleware call automatically captures all incoming HTTP requests, traces request flow, and exports telemetry data to your configured backend.

What is Beego?

Beego is an open-source web framework written in Go that follows the Model-View-Controller (MVC) architectural pattern. It provides a comprehensive set of tools for building web applications and APIs.

Beego's key features include:

• Full MVC architecture with auto-routing
• Built-in ORM for database operations
• Session management and caching
• Logging, configuration, and task scheduling modules
• Hot-reload during development

What is OpenTelemetry?

OpenTelemetry is an open-source observability framework that aims to standardize and simplify the collection, processing, and export of telemetry data from applications and systems.

OpenTelemetry enables developers to instrument their code and collect telemetry data, which can then be exported to various OpenTelemetry backends or observability platforms for analysis and visualization. The OpenTelemetry architecture provides a modular, vendor-neutral approach to observability.

Beego instrumentation

OpenTelemetry Beego instrumentation (otelbeego) provides automatic tracing for your Beego applications. It captures HTTP request details, timing information, and error states without requiring manual instrumentation.

To install otelbeego instrumentation:

go get go.opentelemetry.io/contrib/instrumentation/github.com/astaxie/beego/otelbeego

• Example
• Reference

Usage

You can instrument Beego by creating an OpenTelemetry middleware and passing it to RunWithMiddleWares:

import (
    "github.com/astaxie/beego"
    "go.opentelemetry.io/contrib/instrumentation/github.com/astaxie/beego/otelbeego"
)

func main() {
    mware := otelbeego.NewOTelBeegoMiddleWare("my-service")

    beego.Router("/api/users", &UserController{})
    beego.Router("/api/orders", &OrderController{})
    beego.RunWithMiddleWares(":8080", mware)
}

Once instrumented, otelbeego automatically creates spans for each incoming HTTP request, capturing method, route, status code, and timing information.

Middleware options

The otelbeego middleware supports several configuration options:

Filtering health checks

Use the WithFilter option to exclude certain endpoints from tracing:

import (
    "net/http"

    "github.com/astaxie/beego"
    "go.opentelemetry.io/contrib/instrumentation/github.com/astaxie/beego/otelbeego"
)

mware := otelbeego.NewOTelBeegoMiddleWare("my-service",
    otelbeego.WithFilter(func(r *http.Request) bool {
        // Return true to trace, false to skip
        return r.URL.Path != "/health" && r.URL.Path != "/ready"
    }),
)
beego.RunWithMiddleWares(":8080", mware)

Custom tracer provider

For more control over telemetry collection, you can specify a custom provider:

import (
    "github.com/astaxie/beego"
    "go.opentelemetry.io/contrib/instrumentation/github.com/astaxie/beego/otelbeego"
    "go.opentelemetry.io/otel"
)

mware := otelbeego.NewOTelBeegoMiddleWare("my-service",
    otelbeego.WithTracerProvider(otel.GetTracerProvider()),
    otelbeego.WithMeterProvider(otel.GetMeterProvider()),
)
beego.RunWithMiddleWares(":8080", mware)

Instrumenting template rendering

To instrument template rendering, disable autorender and use helpers from otelbeego package:

import (
    "github.com/astaxie/beego"
    "go.opentelemetry.io/contrib/instrumentation/github.com/astaxie/beego/otelbeego"
)

func init() {
    beego.BConfig.WebConfig.AutoRender = false
}

func (c *MainController) Get() {
    // Creates a child span for template rendering
    err := otelbeego.Render(&c.Controller)
    if err != nil {
        c.Abort("500")
    }
}

Available render helpers:

• otelbeego.Render - Render template with tracing
• otelbeego.RenderBytes - Render template to bytes with tracing
• otelbeego.RenderString - Render template to string with tracing

Creating custom spans

In addition to automatic instrumentation, you can create custom spans to trace specific operations within your controllers:

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/codes"
)

var tracer = otel.Tracer("my-service")

func (c *UserController) Get() {
    ctx := c.Ctx.Request.Context()

    // Create a custom span for database operation
    ctx, span := tracer.Start(ctx, "fetch-user-from-database")
    defer span.End()

    userID := c.Ctx.Input.Param(":id")
    span.SetAttributes(attribute.String("user.id", userID))

    user, err := db.FindUser(ctx, userID)
    if err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, err.Error())
        c.Abort("500")
        return
    }

    span.SetAttributes(attribute.Bool("user.found", user != nil))
    c.Data["json"] = user
    c.ServeJSON()
}

Error handling

OpenTelemetry Beego instrumentation automatically captures panics and errors. You can also manually record errors in your controllers:

import (
    "go.opentelemetry.io/otel/codes"
    "go.opentelemetry.io/otel/trace"
)

func (c *OrderController) Post() {
    // Get the span from the request context
    span := trace.SpanFromContext(c.Ctx.Request.Context())

    order, err := processOrder(c.Ctx.Request.Context())
    if err != nil {
        // Record the error in the span
        span.RecordError(err)
        span.SetStatus(codes.Error, "order processing failed")
        c.Abort("500")
        return
    }

    c.Data["json"] = order
    c.ServeJSON()
}

What is Uptrace?

Uptrace is an OpenTelemetry APM that supports distributed tracing, metrics, and logs. You can use it to monitor applications and troubleshoot issues.

Uptrace comes with an intuitive query builder, rich dashboards, alerting rules with notifications, and integrations for most languages and frameworks.

Uptrace can process billions of spans and metrics on a single server and allows you to monitor your applications at 10x lower cost.

In just a few minutes, you can try Uptrace by visiting the cloud demo (no login required) or running it locally with Docker. The source code is available on GitHub.

FAQ

What is otelbeego? The otelbeego package is the official OpenTelemetry instrumentation for Beego framework. It provides middleware that automatically creates spans for incoming HTTP requests, capturing method, route, status code, and timing information.

How do I filter health check endpoints? Use the WithFilter option when creating the middleware. Return false for paths like /health or /ready to skip tracing those requests.

Does otelbeego work with Beego's built-in filters? Yes, otelbeego works alongside Beego's built-in filters and middleware. The OpenTelemetry middleware wraps the entire request lifecycle, so all filters and handlers are captured within the trace.

What's the performance impact of otelbeego? The performance impact is minimal. The middleware adds a few microseconds per request for span creation and context propagation, which is negligible for most applications.

Can I use otelbeego with Beego's namespace routing? Yes, the middleware is applied at the server level via RunWithMiddleWares, so all routes including namespaced routes are automatically instrumented.

What's next?

With OpenTelemetry Beego instrumentation in place, you can monitor request latency, track error rates, and trace requests across your distributed systems.

Next steps to enhance your observability:

• Add database instrumentation with GORM or database/sql
• Correlate logs with traces using Zap or slog
• Create custom spans using the OpenTelemetry Go Tracing API
• Explore other Go frameworks like Gin or Echo
• Set up the OpenTelemetry Collector for production deployments