Add v1.13 semantic conventions

CHANGELOG.md

@@ -30,6 +30,18 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   These additions are replacements for the `Instrument` and `InstrumentKind` types from `go.opentelemetry.io/otel/sdk/metric/view`. (#3459)
 - The `Stream` type is added to `go.opentelemetry.io/otel/sdk/metric` to define a metric data stream a view will produce. (#3459)
 - The `AssertHasAttributes` allows instrument authors to test that datapoints returned have appropriate attributes. (#3487)
+- Add the `go.opentelemetry.io/otel/semconv/v1.13.0` package.
+  The package contains semantic conventions from the `v1.13.0` version of the OpenTelemetry specification. (#3499)
+  - The `EndUserAttributesFromHTTPRequest` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is merged into `ClientRequest` and `ServerRequest` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `HTTPAttributesFromHTTPStatusCode` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is merged into `ClientResponse` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `HTTPClientAttributesFromHTTPRequest` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is replaced by `ClientRequest` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `HTTPServerAttributesFromHTTPRequest` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is replaced by `ServerRequest` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `HTTPServerMetricAttributesFromHTTPRequest` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is replaced by `ServerRequest` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `NetAttributesFromHTTPRequest` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is split into `Transport` in `go.opentelemetry.io/otel/semconv/v1.13.0/netconv` and `ClientRequest` or `ServerRequest` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `SpanStatusFromHTTPStatusCode` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is replaced by `ClientStatus` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `SpanStatusFromHTTPStatusCodeAndSpanKind` function in `go.opentelemetry.io/otel/semconv/v1.12.0` is split into `ClientStatus` and `ServerStatus` in `go.opentelemetry.io/otel/semconv/v1.13.0/httpconv`.
+  - The `Client` function is included in `go.opentelemetry.io/otel/semconv/v1.13.0/netconv` to generate attributes for a `net.Conn`.
+  - The `Server` function is included in `go.opentelemetry.io/otel/semconv/v1.13.0/netconv` to generate attributes for a `net.Listener`.
 
 ### Changed
 

RELEASING.md

@@ -6,20 +6,25 @@ New versions of the [OpenTelemetry specification] mean new versions of the `semc
 The `semconv-generate` make target is used for this.
 
 1. Checkout a local copy of the [OpenTelemetry specification] to the desired release tag.
-2. Run the `make semconv-generate ...` target from this repository.
+2. Pull the latest `otel/semconvgen` image: `docker pull otel/semconvgen:latest`
+3. Run the `make semconv-generate ...` target from this repository.
 
 For example,
 
 ```sh
-export TAG="v1.7.0" # Change to the release version you are generating.
+export TAG="v1.13.0" # Change to the release version you are generating.
 export OTEL_SPEC_REPO="/absolute/path/to/opentelemetry-specification"
-git -C "$OTEL_SPEC_REPO" checkout "tags/$TAG"
+git -C "$OTEL_SPEC_REPO" checkout "tags/$TAG" -b "$TAG"
+docker pull otel/semconvgen:latest
 make semconv-generate # Uses the exported TAG and OTEL_SPEC_REPO.
 ```
 
 This should create a new sub-package of [`semconv`](./semconv).
 Ensure things look correct before submitting a pull request to include the addition.
 
+**Note**, the generation code was changed to generate versions >= 1.13.
+To generate versions prior to this, checkout the old release of this repository (i.e. [2fe8861](https://github.com/open-telemetry/opentelemetry-go/commit/2fe8861a24e20088c065b116089862caf9e3cd8b)).
+
 ## Pre-Release
 
 First, decide which module sets will be released and update their versions

internal/tools/semconvkit/main.go

@@ -21,6 +21,7 @@ package main
 import (
 	"embed"
 	"flag"
+	"fmt"
 	"log"
 	"os"
 	"path/filepath"
@@ -32,7 +33,7 @@ var (
 	out = flag.String("output", "./", "output directory")
 	tag = flag.String("tag", "", "OpenTelemetry tagged version")
 
-	//go:embed templates/*.tmpl
+	//go:embed templates/*.tmpl templates/netconv/*.tmpl templates/httpconv/*.tmpl
 	rootFS embed.FS
 )
 
@@ -48,8 +49,8 @@ func (sc SemanticConventions) SemVer() string {
 }
 
 // render renders all templates to the dest directory using the data.
-func render(dest string, data *SemanticConventions) error {
-	tmpls, err := template.ParseFS(rootFS, "templates/*.tmpl")
+func render(src, dest string, data *SemanticConventions) error {
+	tmpls, err := template.ParseFS(rootFS, src)
 	if err != nil {
 		return err
 	}
@@ -78,7 +79,17 @@ func main() {
 
 	sc := &SemanticConventions{TagVer: *tag}
 
-	if err := render(*out, sc); err != nil {
+	if err := render("templates/*.tmpl", *out, sc); err != nil {
+		log.Fatal(err)
+	}
+
+	dest := fmt.Sprintf("%s/netconv", *out)
+	if err := render("templates/netconv/*.tmpl", dest, sc); err != nil {
+		log.Fatal(err)
+	}
+
+	dest = fmt.Sprintf("%s/httpconv", *out)
+	if err := render("templates/httpconv/*.tmpl", dest, sc); err != nil {
 		log.Fatal(err)
 	}
 }

internal/tools/semconvkit/templates/http.go.tmpl

@@ -14,101 +14,8 @@
 
 package semconv // import "go.opentelemetry.io/otel/semconv/{{.TagVer}}"
 
-import (
-	"net/http"
-
-	"go.opentelemetry.io/otel/attribute"
-	"go.opentelemetry.io/otel/codes"
-	"go.opentelemetry.io/otel/semconv/internal"
-	"go.opentelemetry.io/otel/trace"
-)
-
 // HTTP scheme attributes.
 var (
 	HTTPSchemeHTTP  = HTTPSchemeKey.String("http")
 	HTTPSchemeHTTPS = HTTPSchemeKey.String("https")
 )
-
-var sc = &internal.SemanticConventions{
-	EnduserIDKey:                EnduserIDKey,
-	HTTPClientIPKey:             HTTPClientIPKey,
-	HTTPFlavorKey:               HTTPFlavorKey,
-	HTTPHostKey:                 HTTPHostKey,
-	HTTPMethodKey:               HTTPMethodKey,
-	HTTPRequestContentLengthKey: HTTPRequestContentLengthKey,
-	HTTPRouteKey:                HTTPRouteKey,
-	HTTPSchemeHTTP:              HTTPSchemeHTTP,
-	HTTPSchemeHTTPS:             HTTPSchemeHTTPS,
-	HTTPServerNameKey:           HTTPServerNameKey,
-	HTTPStatusCodeKey:           HTTPStatusCodeKey,
-	HTTPTargetKey:               HTTPTargetKey,
-	HTTPURLKey:                  HTTPURLKey,
-	HTTPUserAgentKey:            HTTPUserAgentKey,
-	NetHostIPKey:                NetHostIPKey,
-	NetHostNameKey:              NetHostNameKey,
-	NetHostPortKey:              NetHostPortKey,
-	NetPeerIPKey:                NetPeerIPKey,
-	NetPeerNameKey:              NetPeerNameKey,
-	NetPeerPortKey:              NetPeerPortKey,
-	NetTransportIP:              NetTransportIP,
-	NetTransportOther:           NetTransportOther,
-	NetTransportTCP:             NetTransportTCP,
-	NetTransportUDP:             NetTransportUDP,
-	NetTransportUnix:            NetTransportUnix,
-}
-
-// NetAttributesFromHTTPRequest generates attributes of the net
-// namespace as specified by the OpenTelemetry specification for a
-// span.  The network parameter is a string that net.Dial function
-// from standard library can understand.
-func NetAttributesFromHTTPRequest(network string, request *http.Request) []attribute.KeyValue {
-	return sc.NetAttributesFromHTTPRequest(network, request)
-}
-
-// EndUserAttributesFromHTTPRequest generates attributes of the
-// enduser namespace as specified by the OpenTelemetry specification
-// for a span.
-func EndUserAttributesFromHTTPRequest(request *http.Request) []attribute.KeyValue {
-	return sc.EndUserAttributesFromHTTPRequest(request)
-}
-
-// HTTPClientAttributesFromHTTPRequest generates attributes of the
-// http namespace as specified by the OpenTelemetry specification for
-// a span on the client side.
-func HTTPClientAttributesFromHTTPRequest(request *http.Request) []attribute.KeyValue {
-	return sc.HTTPClientAttributesFromHTTPRequest(request)
-}
-
-// HTTPServerMetricAttributesFromHTTPRequest generates low-cardinality attributes
-// to be used with server-side HTTP metrics.
-func HTTPServerMetricAttributesFromHTTPRequest(serverName string, request *http.Request) []attribute.KeyValue {
-	return sc.HTTPServerMetricAttributesFromHTTPRequest(serverName, request)
-}
-
-// HTTPServerAttributesFromHTTPRequest generates attributes of the
-// http namespace as specified by the OpenTelemetry specification for
-// a span on the server side. Currently, only basic authentication is
-// supported.
-func HTTPServerAttributesFromHTTPRequest(serverName, route string, request *http.Request) []attribute.KeyValue {
-	return sc.HTTPServerAttributesFromHTTPRequest(serverName, route, request)
-}
-
-// HTTPAttributesFromHTTPStatusCode generates attributes of the http
-// namespace as specified by the OpenTelemetry specification for a
-// span.
-func HTTPAttributesFromHTTPStatusCode(code int) []attribute.KeyValue {
-	return sc.HTTPAttributesFromHTTPStatusCode(code)
-}
-
-// SpanStatusFromHTTPStatusCode generates a status code and a message
-// as specified by the OpenTelemetry specification for a span.
-func SpanStatusFromHTTPStatusCode(code int) (codes.Code, string) {
-	return internal.SpanStatusFromHTTPStatusCode(code)
-}
-
-// SpanStatusFromHTTPStatusCodeAndSpanKind generates a status code and a message
-// as specified by the OpenTelemetry specification for a span.
-// Exclude 4xx for SERVER to set the appropriate status.
-func SpanStatusFromHTTPStatusCodeAndSpanKind(code int, spanKind trace.SpanKind) (codes.Code, string) {
-	return internal.SpanStatusFromHTTPStatusCodeAndSpanKind(code, spanKind)
-}

internal/tools/semconvkit/templates/httpconv/http.go.tmpl

@@ -0,0 +1,135 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package httpconv provides OpenTelemetry semantic convetions for the net/http
+// package from the standard library.
+package httpconv // import "go.opentelemetry.io/otel/semconv/{{.TagVer}}/httpconv"
+
+import (
+	"net/http"
+
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/semconv/internal/v2"
+	semconv "go.opentelemetry.io/otel/semconv/{{.TagVer}}"
+)
+
+var (
+	nc = &internal.NetConv{
+		NetHostNameKey:     semconv.NetHostNameKey,
+		NetHostPortKey:     semconv.NetHostPortKey,
+		NetPeerNameKey:     semconv.NetPeerNameKey,
+		NetPeerPortKey:     semconv.NetPeerPortKey,
+		NetSockPeerAddrKey: semconv.NetSockPeerAddrKey,
+		NetSockPeerPortKey: semconv.NetSockPeerPortKey,
+		NetTransportOther:  semconv.NetTransportOther,
+		NetTransportTCP:    semconv.NetTransportTCP,
+		NetTransportUDP:    semconv.NetTransportUDP,
+		NetTransportInProc: semconv.NetTransportInProc,
+	}
+
+	hc = &internal.HTTPConv{
+		NetConv: nc,
+
+		EnduserIDKey:                 semconv.EnduserIDKey,
+		HTTPClientIPKey:              semconv.HTTPClientIPKey,
+		HTTPFlavorKey:                semconv.HTTPFlavorKey,
+		HTTPMethodKey:                semconv.HTTPMethodKey,
+		HTTPRequestContentLengthKey:  semconv.HTTPRequestContentLengthKey,
+		HTTPResponseContentLengthKey: semconv.HTTPResponseContentLengthKey,
+		HTTPRouteKey:                 semconv.HTTPRouteKey,
+		HTTPSchemeHTTP:               semconv.HTTPSchemeHTTP,
+		HTTPSchemeHTTPS:              semconv.HTTPSchemeHTTPS,
+		HTTPStatusCodeKey:            semconv.HTTPStatusCodeKey,
+		HTTPTargetKey:                semconv.HTTPTargetKey,
+		HTTPURLKey:                   semconv.HTTPURLKey,
+		HTTPUserAgentKey:             semconv.HTTPUserAgentKey,
+	}
+)
+
+// ClientResponse returns attributes for an HTTP response received by a client
+// from a server. It will return the following attributes if the related values
+// are defined in resp: "http.status.code", "http.response_content_length".
+//
+// This does not add all OpenTelemetry required attributes for an HTTP event,
+// it assumes ClientRequest was used to create the span with a complete set of
+// attributes. If a complete set of attributes can be generated using the
+// request contained in resp. For example:
+//
+//	append(ClientResponse(resp), ClientRequest(resp.Request)...)
+func ClientResponse(resp http.Response) []attribute.KeyValue {
+	return hc.ClientResponse(resp)
+}
+
+// ClientRequest returns attributes for an HTTP request made by a client. The
+// following attributes are always returned: "http.url", "http.flavor",
+// "http.method", "net.peer.name". The following attributes are returned if the
+// related values are defined in req: "net.peer.port", "http.user_agent",
+// "http.request_content_length", "enduser.id".
+func ClientRequest(req *http.Request) []attribute.KeyValue {
+	return hc.ClientRequest(req)
+}
+
+// ClientStatus returns a span status code and message for an HTTP status code
+// value received by a client.
+func ClientStatus(code int) (codes.Code, string) {
+	return hc.ClientStatus(code)
+}
+
+// ServerRequest returns attributes for an HTTP request received by a server.
+// The following attributes are always returned: "http.method", "http.scheme",
+// "http.flavor", "http.target", "net.host.name". The following attributes are
+// returned if they related values are defined in req: "net.host.port",
+// "net.sock.peer.addr", "net.sock.peer.port", "http.user_agent", "enduser.id",
+// "http.client_ip".
+func ServerRequest(req *http.Request) []attribute.KeyValue {
+	return hc.ServerRequest(req)
+}
+
+// ServerStatus returns a span status code and message for an HTTP status code
+// value returned by a server. Status codes in the 400-499 range are not
+// returned as errors.
+func ServerStatus(code int) (codes.Code, string) {
+	return hc.ServerStatus(code)
+}
+
+// RequestHeader returns the contents of h as attributes.
+//
+// Instrumentation should require an explicit configuration of which headers to
+// captured and then prune what they pass here. Including all headers can be a
+// security risk - explicit configuration helps avoid leaking sensitive
+// information.
+//
+// The User-Agent header is already captured in the http.user_agent attribute
+// from ClientRequest and ServerRequest. Instrumentation may provide an option
+// to capture that header here even though it is not recommended. Otherwise,
+// instrumentation should filter that out of what is passed.
+func RequestHeader(h http.Header) []attribute.KeyValue {
+	return hc.RequestHeader(h)
+}
+
+// ResponseHeader returns the contents of h as attributes.
+//
+// Instrumentation should require an explicit configuration of which headers to
+// captured and then prune what they pass here. Including all headers can be a
+// security risk - explicit configuration helps avoid leaking sensitive
+// information.
+//
+// The User-Agent header is already captured in the http.user_agent attribute
+// from ClientRequest and ServerRequest. Instrumentation may provide an option
+// to capture that header here even though it is not recommended. Otherwise,
+// instrumentation should filter that out of what is passed.
+func ResponseHeader(h http.Header) []attribute.KeyValue {
+	return hc.ResponseHeader(h)
+}

internal/tools/semconvkit/templates/netconv/net.go.tmpl

@@ -0,0 +1,66 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package netconv provides OpenTelemetry semantic convetions for the net
+// package from the standard library.
+package netconv // import "go.opentelemetry.io/otel/semconv/{{.TagVer}}/netconv"
+
+import (
+	"net"
+
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/semconv/internal/v2"
+	semconv "go.opentelemetry.io/otel/semconv/{{.TagVer}}"
+)
+
+var nc = &internal.NetConv{
+	NetHostNameKey:     semconv.NetHostNameKey,
+	NetHostPortKey:     semconv.NetHostPortKey,
+	NetPeerNameKey:     semconv.NetPeerNameKey,
+	NetPeerPortKey:     semconv.NetPeerPortKey,
+	NetSockFamilyKey:   semconv.NetSockFamilyKey,
+	NetSockPeerAddrKey: semconv.NetSockPeerAddrKey,
+	NetSockPeerPortKey: semconv.NetSockPeerPortKey,
+	NetSockHostAddrKey: semconv.NetSockHostAddrKey,
+	NetSockHostPortKey: semconv.NetSockHostPortKey,
+	NetTransportOther:  semconv.NetTransportOther,
+	NetTransportTCP:    semconv.NetTransportTCP,
+	NetTransportUDP:    semconv.NetTransportUDP,
+	NetTransportInProc: semconv.NetTransportInProc,
+}
+
+// Transport returns an attribute describing the transport protocol of the
+// passed network. See the net.Dial for information about acceptable network
+// values.
+func Transport(network string) attribute.KeyValue {
+	return nc.Transport(network)
+}
+
+// Client returns attributes for a client network connection to address. See
+// net.Dial for information about acceptable address values, address should be
+// the same as the one used to create conn. If conn is nil, only network peer
+// attributes will be returned that describe address. Otherwise, the socket
+// level information about conn will also be included.
+func Client(address string, conn net.Conn) []attribute.KeyValue {
+	return nc.Client(address, conn)
+}
+
+// Server returns attributes for a network listener listening at address. See
+// net.Listen for information about acceptable address values, address should
+// be the same as the one used to create ln. If ln is nil, only network host
+// attributes will be returned that describe address. Otherwise, the socket
+// level information about ln will also be included.
+func Server(address string, ln net.Listener) []attribute.KeyValue {
+	return nc.Server(address, ln)
+}