Document httpconv and netconv packages as trace providing only trace …

…semantic convention (open-telemetry#3823)

* Document {http,net}conv pkgs as trace semconv

* Fix spelling error

CHANGELOG.md

@@ -31,6 +31,7 @@ This release drops the compatibility guarantee of [Go 1.18].
 ### Fixed
 
 - Handle empty environment variable as it they were not set. (#3764)
+- Clarify the `httpconv` and `netconv` packages in `go.opentelemetry.io/otel/semconv/*` provide tracing semantic conventions. (#3823)
 
 ### Deprecated
 

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

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry HTTP semantic conventions for
+// tracing telemetry.
 package httpconv // import "go.opentelemetry.io/otel/semconv/{{.TagVer}}/httpconv"
 
 import (
@@ -58,9 +58,10 @@ var (
 	}
 )
 
-// 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".
+// ClientResponse returns trace 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
@@ -72,8 +73,8 @@ 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",
+// ClientRequest returns trace 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".
@@ -87,7 +88,8 @@ func ClientStatus(code int) (codes.Code, string) {
 	return hc.ClientStatus(code)
 }
 
-// ServerRequest returns attributes for an HTTP request received by a server.
+// ServerRequest returns trace attributes for an HTTP request received by a
+// server.
 //
 // The server must be the primary server name if it is known. For example this
 // would be the ServerName directive

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

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry network semantic conventions for
+// tracing telemetry.
 package netconv // import "go.opentelemetry.io/otel/semconv/{{.TagVer}}/netconv"
 
 import (
@@ -40,27 +40,27 @@ var nc = &internal.NetConv{
 	NetTransportInProc: semconv.NetTransportInProc,
 }
 
-// Transport returns an attribute describing the transport protocol of the
+// Transport returns a trace 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.
+// Client returns trace 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.
+// Server returns trace 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)
 }

semconv/v1.13.0/httpconv/http.go

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry HTTP semantic conventions for
+// tracing telemetry.
 package httpconv // import "go.opentelemetry.io/otel/semconv/v1.13.0/httpconv"
 
 import (
@@ -58,9 +58,10 @@ var (
 	}
 )
 
-// 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".
+// ClientResponse returns trace 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
@@ -72,8 +73,8 @@ 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",
+// ClientRequest returns trace 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".
@@ -87,7 +88,8 @@ func ClientStatus(code int) (codes.Code, string) {
 	return hc.ClientStatus(code)
 }
 
-// ServerRequest returns attributes for an HTTP request received by a server.
+// ServerRequest returns trace attributes for an HTTP request received by a
+// server.
 //
 // The server must be the primary server name if it is known. For example this
 // would be the ServerName directive

semconv/v1.13.0/netconv/net.go

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry network semantic conventions for
+// tracing telemetry.
 package netconv // import "go.opentelemetry.io/otel/semconv/v1.13.0/netconv"
 
 import (
@@ -40,27 +40,27 @@ var nc = &internal.NetConv{
 	NetTransportInProc: semconv.NetTransportInProc,
 }
 
-// Transport returns an attribute describing the transport protocol of the
+// Transport returns a trace 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.
+// Client returns trace 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.
+// Server returns trace 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)
 }

semconv/v1.14.0/httpconv/http.go

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry HTTP semantic conventions for
+// tracing telemetry.
 package httpconv // import "go.opentelemetry.io/otel/semconv/v1.14.0/httpconv"
 
 import (
@@ -58,9 +58,10 @@ var (
 	}
 )
 
-// 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".
+// ClientResponse returns trace 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
@@ -72,8 +73,8 @@ 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",
+// ClientRequest returns trace 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".
@@ -87,7 +88,8 @@ func ClientStatus(code int) (codes.Code, string) {
 	return hc.ClientStatus(code)
 }
 
-// ServerRequest returns attributes for an HTTP request received by a server.
+// ServerRequest returns trace attributes for an HTTP request received by a
+// server.
 //
 // The server must be the primary server name if it is known. For example this
 // would be the ServerName directive

semconv/v1.14.0/netconv/net.go

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry network semantic conventions for
+// tracing telemetry.
 package netconv // import "go.opentelemetry.io/otel/semconv/v1.14.0/netconv"
 
 import (
@@ -40,27 +40,27 @@ var nc = &internal.NetConv{
 	NetTransportInProc: semconv.NetTransportInProc,
 }
 
-// Transport returns an attribute describing the transport protocol of the
+// Transport returns a trace 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.
+// Client returns trace 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.
+// Server returns trace 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)
 }

semconv/v1.15.0/httpconv/http.go

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry HTTP semantic conventions for
+// tracing telemetry.
 package httpconv // import "go.opentelemetry.io/otel/semconv/v1.15.0/httpconv"
 
 import (
@@ -58,9 +58,10 @@ var (
 	}
 )
 
-// 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".
+// ClientResponse returns trace 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
@@ -72,8 +73,8 @@ 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",
+// ClientRequest returns trace 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".
@@ -87,7 +88,8 @@ func ClientStatus(code int) (codes.Code, string) {
 	return hc.ClientStatus(code)
 }
 
-// ServerRequest returns attributes for an HTTP request received by a server.
+// ServerRequest returns trace attributes for an HTTP request received by a
+// server.
 //
 // The server must be the primary server name if it is known. For example this
 // would be the ServerName directive

semconv/v1.15.0/netconv/net.go

@@ -12,8 +12,8 @@
 // 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 provides OpenTelemetry network semantic conventions for
+// tracing telemetry.
 package netconv // import "go.opentelemetry.io/otel/semconv/v1.15.0/netconv"
 
 import (
@@ -40,27 +40,27 @@ var nc = &internal.NetConv{
 	NetTransportInProc: semconv.NetTransportInProc,
 }
 
-// Transport returns an attribute describing the transport protocol of the
+// Transport returns a trace 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.
+// Client returns trace 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.
+// Server returns trace 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)
 }