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