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