apmhttp

func ClientRequestName ¶

func ClientRequestName(req *http.Request) string

ClientRequestName returns the span name for the client request, req.

func FormatTraceparentHeader ¶

func FormatTraceparentHeader(c apm.TraceContext) string

FormatTraceparentHeader formats the given trace context as a traceparent header.

func IgnoreNone ¶

func IgnoreNone(*http.Request) bool

IgnoreNone is a RequestIgnorerFunc which ignores no requests.

func ParseTraceparentHeader ¶

func ParseTraceparentHeader(h string) (apm.TraceContext, error)

ParseTraceparentHeader parses the given header, which is expected to be in the W3C Trace-Context traceparent format according to W3C Editor's Draft 23 May 2018:

https://w3c.github.io/trace-context/#traceparent-field

Note that the returned TraceContext's Trace and Span fields are not necessarily valid. The caller must decide whether or not it wishes to disregard invalid trace/span IDs, and validate them as required using their provided Validate methods.

The returned TraceContext's TraceState field will be the empty value. Use ParseTracestateHeader to parse that separately.

func ParseTracestateHeader ¶ added in v1.7.0

func ParseTracestateHeader(h ...string) (apm.TraceState, error)

ParseTracestateHeader parses the given header, which is expected to be in the W3C Trace-Context tracestate format according to W3C Editor's Draft 18 Nov 2019:

https://w3c.github.io/trace-context/#tracestate-header

Note that the returned TraceState is not necessarily valid. The caller must decide whether or not it wishes to disregard invalid tracestate entries, and validate them as required using their provided Validate methods.

Multiple header values may be presented, in which case they will be treated as if they are concatenated together with commas.

func RequestWithContext ¶

func RequestWithContext(ctx context.Context, req *http.Request) *http.Request

RequestWithContext is equivalent to req.WithContext, except that the URL pointer is copied, rather than the contents.

func ServerRequestName ¶

func ServerRequestName(req *http.Request) string

ServerRequestName returns the transaction name for the server request, req.

func SetContext ¶

func SetContext(ctx *apm.Context, req *http.Request, resp *Response, body *apm.BodyCapturer)

SetContext sets the context for a transaction or error using information from req, resp, and body.

func SetHeaders ¶ added in v1.14.0

func SetHeaders(req *http.Request, traceContext apm.TraceContext, propagateLegacyHeader bool)

SetHeaders sets traceparent and tracestate headers on an http request.

func SetTransactionContext ¶

func SetTransactionContext(tx *apm.Transaction, req *http.Request, resp *Response, body *apm.BodyCapturer)

SetTransactionContext sets tx.Result and, if the transaction is being sampled, sets tx.Context with information from req, resp, and body.

func StartTransaction ¶

func StartTransaction(tracer *apm.Tracer, name string, req *http.Request) (*apm.Transaction, *http.Request)

StartTransaction returns a new Transaction with name, created with tracer, and taking trace context from req.

If the transaction is not ignored, the request will be returned with the transaction added to its context.

DEPRECATED. Use StartTransactionWithBody instead.

func StartTransactionWithBody ¶ added in v1.12.0

func StartTransactionWithBody(tracer *apm.Tracer, name string, req *http.Request) (*apm.Transaction, *apm.BodyCapturer, *http.Request)

StartTransactionWithBody returns a new Transaction with name, created with tracer, and taking trace context from req.

If the transaction is not ignored, the request and the request body capturer will be returned with the transaction added to its context.

func StatusCodeResult ¶

func StatusCodeResult(statusCode int) string

StatusCodeResult returns the transaction result value to use for the given status code.

func UnknownRouteRequestName ¶ added in v1.4.0

func UnknownRouteRequestName(req *http.Request) string

UnknownRouteRequestName returns the transaction name for the server request, req, when the route could not be determined.

func Wrap ¶

func Wrap(h http.Handler, o ...ServerOption) http.Handler

Wrap returns an http.Handler wrapping h, reporting each request as a transaction to Elastic APM.

By default, the returned Handler will use apm.DefaultTracer. Use WithTracer to specify an alternative tracer.

By default, the returned Handler will recover panics, reporting them to the configured tracer. To override this behaviour, use WithRecovery.

func WrapClient ¶

func WrapClient(c *http.Client, o ...ClientOption) *http.Client

WrapClient returns a new *http.Client with all fields copied across, and the Transport field wrapped with WrapRoundTripper such that client requests are reported as spans to Elastic APM if their context contains a sampled transaction.

Spans are started just before the request is sent, and ended immediately if the request returned an error (e.g. due to socket timeout, but not a valid response with a non-200 status code), or otherwise when the response body is fully consumed or closed.

If c is nil, then http.DefaultClient is wrapped.

// Licensed to Elasticsearch B.V. under one or more contributor
// license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright
// ownership. Elasticsearch B.V. licenses this file to you under
// the Apache License, Version 2.0 (the "License"); you may
// not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"net/http/httptest"
	"time"

	"go.elastic.co/apm/apmtest"
	"go.elastic.co/apm/module/apmhttp"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/slow", serveSlowly)
	server := httptest.NewServer(mux)
	defer server.Close()

	// Wrap the HTTP client with apmhttp.WrapClient. When using the
	// wrapped client, any request whose context contains a transaction
	// will have a span reported.
	client := apmhttp.WrapClient(http.DefaultClient)
	slowReq, _ := http.NewRequest("GET", server.URL+"/slow", nil)
	errorReq, _ := http.NewRequest("GET", "http://testing.invalid", nil)

	_, spans, _ := apmtest.WithTransaction(func(ctx context.Context) {
		// Propagate context with the outgoing request.
		req := slowReq.WithContext(ctx)
		resp, err := client.Do(req)
		if err != nil {
			log.Fatal(err)
		}

		// In the case where the request succeeds (i.e. no error
		// was returned above; unrelated to the HTTP status code),
		// the span is not ended until the body is consumed.
		body, err := ioutil.ReadAll(resp.Body)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("response: %s\n", body)

		// Send a request to a URL with an unresolvable host. This
		// will cause the entire request to fail, immediately
		// ending the span.
		resp, err = client.Do(errorReq.WithContext(ctx))
		if err != nil {
			fmt.Println("error occurred")
		} else {
			resp.Body.Close()
		}
	})

	if len(spans) != 2 {
		fmt.Println(len(spans), "spans")
	} else {
		for i, span := range spans {
			const expectedFloor = 250 * time.Millisecond
			if time.Duration(span.Duration*float64(time.Millisecond)) >= expectedFloor {
				// This is the expected case (see output below). As noted
				// previously, the span is only ended once the response body
				// has been consumed (or closed).
				fmt.Printf("span #%d duration >= %s\n", i+1, expectedFloor)
			} else {
				fmt.Printf("span #%d duration < %s\n", i+1, expectedFloor)
			}
		}
	}

}

func serveSlowly(w http.ResponseWriter, req *http.Request) {
	w.WriteHeader(http.StatusTeapot)
	if f, ok := w.(http.Flusher); ok {
		f.Flush()
	}
	time.Sleep(250 * time.Millisecond)
	w.Write([]byte("*yawn*"))
}

Output:


response: *yawn*
error occurred
span #1 duration >= 250ms
span #2 duration < 250ms

func WrapRoundTripper ¶

func WrapRoundTripper(r http.RoundTripper, o ...ClientOption) http.RoundTripper

WrapRoundTripper returns an http.RoundTripper wrapping r, reporting each request as a span to Elastic APM, if the request's context contains a sampled transaction.

If r is nil, then http.DefaultTransport is wrapped.