Documentation
¶
Overview ¶
Package echo provides functions to trace the labstack/echo package (https://github.com/labstack/echo).
Example ¶
To start tracing requests, add the trace middleware to your echo router.
package main
import (
echotrace "github.com/DataDog/dd-trace-go/contrib/labstack/echo.v5/v2"
"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
"github.com/labstack/echo/v5"
)
func main() {
tracer.Start()
defer tracer.Stop()
r := echo.New()
// Use the tracer middleware with your desired service name.
r.Use(echotrace.Middleware(echotrace.WithService("my-web-app")))
// Set up an endpoint.
r.GET("/hello", func(c *echo.Context) error {
return c.String(200, "hello world!")
})
// ...and listen for incoming requests
r.Start(":8080")
}
Output:
Example (SpanFromContext) ¶
An example illustrating tracing a child operation within the main context.
package main
import (
echotrace "github.com/DataDog/dd-trace-go/contrib/labstack/echo.v5/v2"
"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
"github.com/labstack/echo/v5"
)
func main() {
tracer.Start()
defer tracer.Stop()
// Create a new instance of echo
r := echo.New()
// Use the tracer middleware with your desired service name.
r.Use(echotrace.Middleware(echotrace.WithService("image-encoder")))
// Set up some endpoints.
r.GET("/image/encode", func(c *echo.Context) error {
// create a child span to track an operation
span, _ := tracer.StartSpanFromContext(c.Request().Context(), "image.encode")
// encode an image ...
// finish the child span
span.Finish()
return c.String(200, "ok!")
})
}
Output:
Index ¶
- func Middleware(opts ...Option) echo.MiddlewareFunc
- func OnAddRoute(route echo.Route) error
- func Wrap(e *echo.Echo, opts ...Option) *echo.Echo
- type IgnoreRequestFunc
- type Option
- type OptionFn
- func NoDebugStack() OptionFn
- func WithCustomTag(key string, value any) OptionFn
- func WithErrorCheck(errCheck func(error) bool) OptionFn
- func WithErrorTranslator(fn func(err error) (*echo.HTTPError, bool)) OptionFn
- func WithHeaderTags(headers []string) OptionFn
- func WithIgnoreRequest(ignoreRequestFunc IgnoreRequestFunc) OptionFn
- func WithService(name string) OptionFn
- func WithStatusCheck(fn func(statusCode int) bool) OptionFn
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Middleware ¶
func Middleware(opts ...Option) echo.MiddlewareFunc
Middleware returns echo middleware that traces incoming requests. Prefer Wrap for typical setups — it also enables route registration tracking and AppSec body monitoring. Use Middleware directly when you need scoped tracing (e.g. on a sub-group) or when those features should not be enabled globally.
func OnAddRoute ¶
OnAddRoute is used as echo.Echo.OnAddRoute value to automatically collect route information as it is being registered in the router, so they appear in the API Catalog even if they receive no traffic.
The collection can be disabled at runtime by setting `DD_API_SECURITY_ENDPOINT_COLLECTION_ENABLED` to a false-ey value.
func Wrap ¶
Wrap configures the provided echo.Echo and returns it. It:
- registers Middleware via echo.Echo.Use,
- sets echo.Echo.OnAddRoute to OnAddRoute for API Catalog reporting,
- lazily wraps echo.Echo.Binder on the first request, preserving any user-configured Binder as the inner delegate (see notes below).
Wrap must be called before starting the server (e.g. echo.Echo.Start) and before any concurrent access to the echo.Echo instance. Echo itself forbids mutating Echo fields after the server has started.
AppSec body monitoring — differences with the echo.v4 integration:
In echo v4, AppSec wrapped the echo.Context interface at request time, so it was independent of echo.Echo.Binder reassignment. echo.Context in echo v5 is a concrete struct that cannot be wrapped, so AppSec must intercept body parsing via echo.Echo.Binder instead. To preserve flexibility, Wrap installs the AppSec Binder wrap lazily on the first request: any custom Binder assigned to echo.Echo.Binder between Wrap and the first request is captured as the inner delegate, and both run on every Bind call (your Binder first, then AppSec monitoring).
Caveat: reassigning echo.Echo.Binder after the first request has been served will silently disable AppSec body monitoring. Echo itself forbids mutating Echo instance fields after the server has started; this falls under that same restriction.
It is recommended to use Wrap if you want to benefit from future tracer features that require additional properties to be configured without having to update your code.
Types ¶
type IgnoreRequestFunc ¶
IgnoreRequestFunc determines if tracing will be skipped for a request.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option describes options for the Echo.v5 integration.
type OptionFn ¶
type OptionFn func(*config)
OptionFn represents options applicable to Middleware.
func NoDebugStack ¶
func NoDebugStack() OptionFn
NoDebugStack prevents stack traces from being attached to spans finishing with an error. This is useful in situations where errors are frequent and performance is critical.
func WithCustomTag ¶
WithCustomTag will attach the value to the span tagged by the key. Standard span tags cannot be replaced.
func WithErrorCheck ¶
WithErrorCheck sets the func which determines if err would be ignored (if it returns true, the error is not tagged). This function also checks the errors created from the WithStatusCheck option.
func WithErrorTranslator ¶
WithErrorTranslator sets a function to translate Go errors into echo Errors. This is used for extracting the HTTP response status code.
func WithHeaderTags ¶
WithHeaderTags enables the integration to attach HTTP request headers as span tags. Warning: Using this feature can risk exposing sensitive data such as authorization tokens to Datadog. Special headers can not be sub-selected. E.g., an entire Cookie header would be transmitted, without the ability to choose specific Cookies.
func WithIgnoreRequest ¶
func WithIgnoreRequest(ignoreRequestFunc IgnoreRequestFunc) OptionFn
WithIgnoreRequest sets a function which determines if tracing will be skipped for a given request.
func WithService ¶
WithService sets the given service name for the system.
func WithStatusCheck ¶
WithStatusCheck specifies a function fn which reports whether the passed statusCode should be considered an error.
Source Files