Debian Codegraph @

semconv/v1.17.0/httpconv/http.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 // Package httpconv provides OpenTelemetry HTTP semantic conventions for
5 // tracing telemetry.
6 package httpconv // import "go.opentelemetry.io/otel/semconv/v1.17.0/httpconv"
7
8 import (
9 "net/http"
10
11 "go.opentelemetry.io/otel/attribute"
12 "go.opentelemetry.io/otel/codes"
13 "go.opentelemetry.io/otel/semconv/internal/v2"
14 semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
15 )
16
17 var (
18 nc = &internal.NetConv{
19 NetHostNameKey: semconv.NetHostNameKey,
20 NetHostPortKey: semconv.NetHostPortKey,
21 NetPeerNameKey: semconv.NetPeerNameKey,
22 NetPeerPortKey: semconv.NetPeerPortKey,
23 NetSockPeerAddrKey: semconv.NetSockPeerAddrKey,
24 NetSockPeerPortKey: semconv.NetSockPeerPortKey,
25 NetTransportOther: semconv.NetTransportOther,
26 NetTransportTCP: semconv.NetTransportTCP,
27 NetTransportUDP: semconv.NetTransportUDP,
28 NetTransportInProc: semconv.NetTransportInProc,
29 }
30
31 hc = &internal.HTTPConv{
32 NetConv: nc,
33
34 EnduserIDKey: semconv.EnduserIDKey,
35 HTTPClientIPKey: semconv.HTTPClientIPKey,
36 HTTPFlavorKey: semconv.HTTPFlavorKey,
37 HTTPMethodKey: semconv.HTTPMethodKey,
38 HTTPRequestContentLengthKey: semconv.HTTPRequestContentLengthKey,
39 HTTPResponseContentLengthKey: semconv.HTTPResponseContentLengthKey,
40 HTTPRouteKey: semconv.HTTPRouteKey,
41 HTTPSchemeHTTP: semconv.HTTPSchemeHTTP,
42 HTTPSchemeHTTPS: semconv.HTTPSchemeHTTPS,
43 HTTPStatusCodeKey: semconv.HTTPStatusCodeKey,
44 HTTPTargetKey: semconv.HTTPTargetKey,
45 HTTPURLKey: semconv.HTTPURLKey,
46 HTTPUserAgentKey: semconv.HTTPUserAgentKey,
47 }
48 )
49
50 // ClientResponse returns trace attributes for an HTTP response received by a
51 // client from a server. It will return the following attributes if the related
52 // values are defined in resp: "http.status.code",
53 // "http.response_content_length".
54 //
55 // This does not add all OpenTelemetry required attributes for an HTTP event,
56 // it assumes ClientRequest was used to create the span with a complete set of
57 // attributes. If a complete set of attributes can be generated using the
58 // request contained in resp. For example:
59 //
60 // append(ClientResponse(resp), ClientRequest(resp.Request)...)
61 func ClientResponse(resp *http.Response) []attribute.KeyValue {
62 return hc.ClientResponse(resp)
63 }
64
65 // ClientRequest returns trace attributes for an HTTP request made by a client.
66 // The following attributes are always returned: "http.url", "http.flavor",
67 // "http.method", "net.peer.name". The following attributes are returned if the
68 // related values are defined in req: "net.peer.port", "http.user_agent",
69 // "http.request_content_length", "enduser.id".
70 func ClientRequest(req *http.Request) []attribute.KeyValue {
71 return hc.ClientRequest(req)
72 }
73
74 // ClientStatus returns a span status code and message for an HTTP status code
75 // value received by a client.
76 func ClientStatus(code int) (codes.Code, string) {
77 return hc.ClientStatus(code)
78 }
79
80 // ServerRequest returns trace attributes for an HTTP request received by a
81 // server.
82 //
83 // The server must be the primary server name if it is known. For example this
84 // would be the ServerName directive
85 // (https://httpd.apache.org/docs/2.4/mod/core.html#servername) for an Apache
86 // server, and the server_name directive
87 // (http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name) for an
88 // nginx server. More generically, the primary server name would be the host
89 // header value that matches the default virtual host of an HTTP server. It
90 // should include the host identifier and if a port is used to route to the
91 // server that port identifier should be included as an appropriate port
92 // suffix.
93 //
94 // If the primary server name is not known, server should be an empty string.
95 // The req Host will be used to determine the server instead.
96 //
97 // The following attributes are always returned: "http.method", "http.scheme",
98 // "http.flavor", "http.target", "net.host.name". The following attributes are
99 // returned if they related values are defined in req: "net.host.port",
100 // "net.sock.peer.addr", "net.sock.peer.port", "http.user_agent", "enduser.id",
101 // "http.client_ip".
102 func ServerRequest(server string, req *http.Request) []attribute.KeyValue {
103 return hc.ServerRequest(server, req)
104 }
105
106 // ServerStatus returns a span status code and message for an HTTP status code
107 // value returned by a server. Status codes in the 400-499 range are not
108 // returned as errors.
109 func ServerStatus(code int) (codes.Code, string) {
110 return hc.ServerStatus(code)
111 }
112
113 // RequestHeader returns the contents of h as attributes.
114 //
115 // Instrumentation should require an explicit configuration of which headers to
116 // captured and then prune what they pass here. Including all headers can be a
117 // security risk - explicit configuration helps avoid leaking sensitive
118 // information.
119 //
120 // The User-Agent header is already captured in the http.user_agent attribute
121 // from ClientRequest and ServerRequest. Instrumentation may provide an option
122 // to capture that header here even though it is not recommended. Otherwise,
123 // instrumentation should filter that out of what is passed.
124 func RequestHeader(h http.Header) []attribute.KeyValue {
125 return hc.RequestHeader(h)
126 }
127
128 // ResponseHeader returns the contents of h as attributes.
129 //
130 // Instrumentation should require an explicit configuration of which headers to
131 // captured and then prune what they pass here. Including all headers can be a
132 // security risk - explicit configuration helps avoid leaking sensitive
133 // information.
134 //
135 // The User-Agent header is already captured in the http.user_agent attribute
136 // from ClientRequest and ServerRequest. Instrumentation may provide an option
137 // to capture that header here even though it is not recommended. Otherwise,
138 // instrumentation should filter that out of what is passed.
139 func ResponseHeader(h http.Header) []attribute.KeyValue {
140 return hc.ResponseHeader(h)
141 }