Debian Codegraph @

semconv/v1.20.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.20.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/v4"
14 semconv "go.opentelemetry.io/otel/semconv/v1.20.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 NetProtocolNameKey: semconv.NetProtocolNameKey,
37 NetProtocolVersionKey: semconv.NetProtocolVersionKey,
38 HTTPMethodKey: semconv.HTTPMethodKey,
39 HTTPRequestContentLengthKey: semconv.HTTPRequestContentLengthKey,
40 HTTPResponseContentLengthKey: semconv.HTTPResponseContentLengthKey,
41 HTTPRouteKey: semconv.HTTPRouteKey,
42 HTTPSchemeHTTP: semconv.HTTPSchemeHTTP,
43 HTTPSchemeHTTPS: semconv.HTTPSchemeHTTPS,
44 HTTPStatusCodeKey: semconv.HTTPStatusCodeKey,
45 HTTPTargetKey: semconv.HTTPTargetKey,
46 HTTPURLKey: semconv.HTTPURLKey,
47 UserAgentOriginalKey: semconv.UserAgentOriginalKey,
48 }
49 )
50
51 // ClientResponse returns trace attributes for an HTTP response received by a
52 // client from a server. It will return the following attributes if the related
53 // values are defined in resp: "http.status.code",
54 // "http.response_content_length".
55 //
56 // This does not add all OpenTelemetry required attributes for an HTTP event,
57 // it assumes ClientRequest was used to create the span with a complete set of
58 // attributes. If a complete set of attributes can be generated using the
59 // request contained in resp. For example:
60 //
61 // append(ClientResponse(resp), ClientRequest(resp.Request)...)
62 func ClientResponse(resp *http.Response) []attribute.KeyValue {
63 return hc.ClientResponse(resp)
64 }
65
66 // ClientRequest returns trace attributes for an HTTP request made by a client.
67 // The following attributes are always returned: "http.url",
68 // "net.protocol.(name|version)", "http.method", "net.peer.name".
69 // The following attributes are returned if the related values are defined
70 // in req: "net.peer.port", "http.user_agent", "http.request_content_length",
71 // "enduser.id".
72 func ClientRequest(req *http.Request) []attribute.KeyValue {
73 return hc.ClientRequest(req)
74 }
75
76 // ClientStatus returns a span status code and message for an HTTP status code
77 // value received by a client.
78 func ClientStatus(code int) (codes.Code, string) {
79 return hc.ClientStatus(code)
80 }
81
82 // ServerRequest returns trace attributes for an HTTP request received by a
83 // server.
84 //
85 // The server must be the primary server name if it is known. For example this
86 // would be the ServerName directive
87 // (https://httpd.apache.org/docs/2.4/mod/core.html#servername) for an Apache
88 // server, and the server_name directive
89 // (http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name) for an
90 // nginx server. More generically, the primary server name would be the host
91 // header value that matches the default virtual host of an HTTP server. It
92 // should include the host identifier and if a port is used to route to the
93 // server that port identifier should be included as an appropriate port
94 // suffix.
95 //
96 // If the primary server name is not known, server should be an empty string.
97 // The req Host will be used to determine the server instead.
98 //
99 // The following attributes are always returned: "http.method", "http.scheme",
100 // ""net.protocol.(name|version)", "http.target", "net.host.name".
101 // The following attributes are returned if they related values are defined
102 // in req: "net.host.port", "net.sock.peer.addr", "net.sock.peer.port",
103 // "user_agent.original", "enduser.id", "http.client_ip".
104 func ServerRequest(server string, req *http.Request) []attribute.KeyValue {
105 return hc.ServerRequest(server, req)
106 }
107
108 // ServerStatus returns a span status code and message for an HTTP status code
109 // value returned by a server. Status codes in the 400-499 range are not
110 // returned as errors.
111 func ServerStatus(code int) (codes.Code, string) {
112 return hc.ServerStatus(code)
113 }
114
115 // RequestHeader returns the contents of h as attributes.
116 //
117 // Instrumentation should require an explicit configuration of which headers to
118 // captured and then prune what they pass here. Including all headers can be a
119 // security risk - explicit configuration helps avoid leaking sensitive
120 // information.
121 //
122 // The User-Agent header is already captured in the user_agent.original attribute
123 // from ClientRequest and ServerRequest. Instrumentation may provide an option
124 // to capture that header here even though it is not recommended. Otherwise,
125 // instrumentation should filter that out of what is passed.
126 func RequestHeader(h http.Header) []attribute.KeyValue {
127 return hc.RequestHeader(h)
128 }
129
130 // ResponseHeader returns the contents of h as attributes.
131 //
132 // Instrumentation should require an explicit configuration of which headers to
133 // captured and then prune what they pass here. Including all headers can be a
134 // security risk - explicit configuration helps avoid leaking sensitive
135 // information.
136 //
137 // The User-Agent header is already captured in the user_agent.original attribute
138 // from ClientRequest and ServerRequest. Instrumentation may provide an option
139 // to capture that header here even though it is not recommended. Otherwise,
140 // instrumentation should filter that out of what is passed.
141 func ResponseHeader(h http.Header) []attribute.KeyValue {
142 return hc.ResponseHeader(h)
143 }