HTTP.md

HTTP Trace

This document explains tracing of HTTP requests with OpenCensus.

Spans

Implementations MUST create a span for outgoing requests at the client and a span for incoming requests at the server.

Span name is formatted as:

• /$path for outgoing requests.
• /($path|$route) for incoming requests.

If route cannot be determined, path is used to name the the span for outgoing requests.

Port MUST be omitted if it is 80 or 443.

Examples of span names:

• /users
• /messages/[:id]
• /users/25f4c31d

Outgoing requests should be a span kind of CLIENT and incoming requests should be a span kind of SERVER.

Propagation

Propagation is how SpanContext is transmitted on the wire in an HTTP request.

Implementations MUST allow users to set their own propagation format and MUST provide an implementation for B3 and TraceContext at least.

If user doesn't set any propagation methods explicitly, TraceContext is used.

In a previous version of this spec, we recommended that B3 be the default. For backwards compatibility, implementations may provide a way for users to "opt in" to the new default explicitly, to avoid a silent change to defaults that could break existing deployments.

The propagation method SHOULD modify a request object to insert a SpanContext or SHOULD be able to extract a SpanContext from a request object.

Status

Implementations MUST set status if HTTP request or response is not successful (e.g. not 2xx). In redirection case, if the client doesn't have autoredirection support, request should be considered successful.

Set status code to UNKNOWN (2) if the reason cannot be inferred at the callsite or from the HTTP status code.

Don't set the status message if the reason can be inferred at the callsite of from the HTTP status code.

Mapping from HTTP status codes to Trace status codes

HTTP code	Trace status code
0...199	2 (UNKNOWN)
200...399	0 (OK)
400 Bad Request	3 (INVALID_ARGUMENT)
504 Gateway Timeout	4 (DEADLINE_EXCEEDED)
404 Not Found	5 (NOT_FOUND)
403 Forbidden	7 (PERMISSION_DENIED)
401 Unauthorized*	16 (UNAUTHENTICATED)
429 Too Many Requests	8 (RESOURCE_EXHAUSTED)
501 Not Implemented	12 (UNIMPLEMENTED)
503 Unavailable	14 (UNAVAILABLE)

Notes: 401 Unauthorized actually means unauthenticated according to RFC 7235, 3.1.

The Status message should be the Reason-Phrase (RFC 2616 6.1.1) from the response status line (if available).

Client errors for client HTTP calls

There are a number of client errors when trying to access http endpoint. Here are examples of mapping those to the OpenCensus status codes.

Client error	Trace status code
DNS resolution failed	2 (UNKNOWN)
Request cancelled by caller	1 (CANCELLED)
URL cannot be parsed	3 (INVALID_ARGUMENT)
Request timed out	1 (DEADLINE_EXCEEDED)

Message events

In the lifetime of an incoming and outgoing request, the following message events SHOULD be created:

• A message event for the request body size if/when determined.
• A message event for the response size if/when determined.

Implementations SHOULD create message event when body size is determined.

-> [time], MessageEventTypeSent, UncompressedByteSize, CompressedByteSize

Implementations SHOULD create message event when response size is determined.

-> [time], MessageEventTypeRecv, UncompressedByteSize, CompressedByteSize

Attributes

Implementations SHOULD set the following attributes on the client and server spans. For a server, request represents the incoming request. For a client, request represents the outgoing request.

All attributes are optional, but collector should make the best effort to collect those.

Attribute name	Description	Type	Example value
"http.host"	Request URL host	string	example.com:779
"http.method"	Request URL method	string	GET
"http.path"	Request URL path. If empty - set to /	/users/25f4c31d
"http.route"	Matched request URL route	string	/users/:userID
"http.user_agent"	Request user-agent. Do not inject attribute if user-agent is empty.	string	HTTPClient/1.2
"http.status_code"	Response status code	int64	200
"http.url"	Absolute request URL	string	https://example.com:779/path/12314/?q=ddds#123

Exporters should always export the collected attributes. Exporters should map the collected attributes to backend's known attributes/labels.

The following table summarizes how OpenCensus attributes maps to the known attributes/labels on supported tracing backends.

OpenCensus attribute	Zipkin	Jaeger	Stackdriver Trace label
"http.host"	"http.host"	"http.host"	"/http/host"
"http.method"	"http.method"	"http.method"	"/http/method"
"http.path"	"http.path"	"http.path"	"/http/path"
"http.route"	"http.route"	"http.route"	"/http/route"
"http.user_agent"	"http.user_agent"	"http.user_agent"	"/http/user_agent"
"http.status_code"	"http.status_code"	"http.status_code"	"/http/status_code"
"http.url"	"http.url"	"http.url"	"/http/url"

References:

• Stackdriver Trace label
• Jaeger/Open Tracing
• Zipkin

Test Cases

Test cases for outgoing http calls are in the file http-out-test-cases.json.

File consists of a set of test cases. Each test case represents outgoing http call, response it receives and the resulting span properties. It looks like this:

{
"name": "Name is populated as a path",
"method": "GET",
"url": "http://{host}:{port}/path/to/resource/",
"headers": {
    "User-Agent": "test-user-agent"
},
"responseCode": 200,
"spanName": "/path/to/resource/",
"spanStatus": "OK",
"spanKind": "Client",
"spanAttributes": {
    "http.path": "/path/to/resource/",
    "http.method": "GET",
    "http.host": "{host}:{port}",
    "http.status_code": "200",
    "http.user_agent": "test-user-agent"
}
}

Where name is the name of the test case. Properties method, url and headers collection represents the outgoing call. The field responseCode describes the response status code.

The rest of the properties describe the span details of the resulting span - it's name, kind, status and attributes.

Sampling

There are two ways to control the Sampler used:

• Controlling the global default Sampler via TraceConfig.
• Pass a specific Sampler as an option to the HTTP plugin. Plugins should support setting a sampler per HTTP request.

Example cases where per-request sampling is useful:

• Having different sampling policy per route
• Having different sampling policy per method
• Filtering out certain paths (e.g. health endpoints) to disable tracing
• Always sampling critical paths
• Sampling based on the custom request header or query parameter

In the following Go example, incoming and outgoing request objects can dynamically inspected to set a sampler.

For outgoing requests:

type Transport struct {
 	// GetStartOptions allows to set start options per request.
	GetStartOptions func(*http.Request) trace.StartOptions

	// ...
}

For incoming requests:

type Handler struct {
 	// GetStartOptions allows to set start options per request.
	GetStartOptions func(*http.Request) trace.StartOptions

	// ...
}