For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to + * the database name. + */ + FaasDatasourceSemanticConvention setFaasDocumentCollection(String faasDocumentCollection); + + /** + * Sets a value for faas.document.operation + * + * @param faasDocumentOperation Describes the type of the operation that was performed on the + * data. + */ + FaasDatasourceSemanticConvention setFaasDocumentOperation(String faasDocumentOperation); + + /** + * Sets a value for faas.document.time + * + * @param faasDocumentTime A string containing the time when the data was accessed in the [ISO + * 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in + * [UTC](https://www.w3.org/TR/NOTE-datetime). + */ + FaasDatasourceSemanticConvention setFaasDocumentTime(String faasDocumentTime); + + /** + * Sets a value for faas.document.name + * + * @param faasDocumentName The document name/table subjected to the operation. + *
For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table + * name. + */ + FaasDatasourceSemanticConvention setFaasDocumentName(String faasDocumentName); +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasDatasourceSpan.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasDatasourceSpan.java new file mode 100644 index 0000000000..8ff2dab2d4 --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasDatasourceSpan.java @@ -0,0 +1,247 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; +import io.opentelemetry.trace.SpanContext; +import io.opentelemetry.trace.Tracer; + +public class FaasDatasourceSpan extends DelegatingSpan implements FaasDatasourceSemanticConvention { + + protected FaasDatasourceSpan(Span span) { + super(span); + } + + /** + * Entry point to generate a {@link FaasDatasourceSpan}. + * + * @param tracer Tracer to use + * @param spanName Name for the {@link Span} + * @return a {@link FaasDatasourceSpan} object. + */ + public static FaasDatasourceSpanBuilder createFaasDatasourceSpan(Tracer tracer, String spanName) { + return new FaasDatasourceSpanBuilder(tracer, spanName); + } + + /** + * Creates a {@link FaasDatasourceSpan} from a {@link FaasSpanSpan}. + * + * @param builder {@link FaasSpanSpan.FaasSpanSpanBuilder} to use. + * @return a {@link FaasDatasourceSpan} object built from a {@link FaasSpanSpan}. + */ + public static FaasDatasourceSpanBuilder createFaasDatasourceSpan( + FaasSpanSpan.FaasSpanSpanBuilder builder) { + // we accept a builder from FaasSpan since FaasDatasource "extends" FaasSpan + return new FaasDatasourceSpanBuilder(builder.getSpanBuilder()); + } + + /** @return the Span used internally */ + @Override + public Span getSpan() { + return this.delegate; + } + + /** Terminates the Span. Here there is the checking for required attributes. */ + @Override + public void end() { + delegate.end(); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + @Override + public FaasDatasourceSemanticConvention setFaasTrigger(String faasTrigger) { + delegate.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + @Override + public FaasDatasourceSemanticConvention setFaasExecution(String faasExecution) { + delegate.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets faas.document.collection. + * + * @param faasDocumentCollection The name of the source on which the triggering operation was + * performed. + *
For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to + * the database name. + */ + @Override + public FaasDatasourceSemanticConvention setFaasDocumentCollection(String faasDocumentCollection) { + delegate.setAttribute("faas.document.collection", faasDocumentCollection); + return this; + } + + /** + * Sets faas.document.operation. + * + * @param faasDocumentOperation Describes the type of the operation that was performed on the + * data. + */ + @Override + public FaasDatasourceSemanticConvention setFaasDocumentOperation(String faasDocumentOperation) { + delegate.setAttribute("faas.document.operation", faasDocumentOperation); + return this; + } + + /** + * Sets faas.document.time. + * + * @param faasDocumentTime A string containing the time when the data was accessed in the [ISO + * 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in + * [UTC](https://www.w3.org/TR/NOTE-datetime). + */ + @Override + public FaasDatasourceSemanticConvention setFaasDocumentTime(String faasDocumentTime) { + delegate.setAttribute("faas.document.time", faasDocumentTime); + return this; + } + + /** + * Sets faas.document.name. + * + * @param faasDocumentName The document name/table subjected to the operation. + *
For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table + * name. + */ + @Override + public FaasDatasourceSemanticConvention setFaasDocumentName(String faasDocumentName) { + delegate.setAttribute("faas.document.name", faasDocumentName); + return this; + } + + /** Builder class for {@link FaasDatasourceSpan}. */ + public static class FaasDatasourceSpanBuilder { + // Protected because maybe we want to extend manually these classes + protected Span.Builder internalBuilder; + + protected FaasDatasourceSpanBuilder(Tracer tracer, String spanName) { + internalBuilder = tracer.spanBuilder(spanName); + } + + public FaasDatasourceSpanBuilder(Span.Builder spanBuilder) { + this.internalBuilder = spanBuilder; + } + + public Span.Builder getSpanBuilder() { + return this.internalBuilder; + } + + /** sets the {@link Span} parent. */ + public FaasDatasourceSpanBuilder setParent(Span parent) { + this.internalBuilder.setParent(parent); + return this; + } + + /** sets the {@link Span} parent. */ + public FaasDatasourceSpanBuilder setParent(SpanContext remoteParent) { + this.internalBuilder.setParent(remoteParent); + return this; + } + + /** this method sets the type of the {@link Span} is only available in the builder. */ + public FaasDatasourceSpanBuilder setKind(Span.Kind kind) { + internalBuilder.setSpanKind(kind); + return this; + } + + /** starts the span */ + public FaasDatasourceSpan start() { + // check for sampling relevant field here, but there are none. + return new FaasDatasourceSpan(this.internalBuilder.startSpan()); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + public FaasDatasourceSpanBuilder setFaasTrigger(String faasTrigger) { + internalBuilder.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + public FaasDatasourceSpanBuilder setFaasExecution(String faasExecution) { + internalBuilder.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets faas.document.collection. + * + * @param faasDocumentCollection The name of the source on which the triggering operation was + * performed. + *
For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB + * to the database name. + */ + public FaasDatasourceSpanBuilder setFaasDocumentCollection(String faasDocumentCollection) { + internalBuilder.setAttribute("faas.document.collection", faasDocumentCollection); + return this; + } + + /** + * Sets faas.document.operation. + * + * @param faasDocumentOperation Describes the type of the operation that was performed on the + * data. + */ + public FaasDatasourceSpanBuilder setFaasDocumentOperation(String faasDocumentOperation) { + internalBuilder.setAttribute("faas.document.operation", faasDocumentOperation); + return this; + } + + /** + * Sets faas.document.time. + * + * @param faasDocumentTime A string containing the time when the data was accessed in the [ISO + * 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in + * [UTC](https://www.w3.org/TR/NOTE-datetime). + */ + public FaasDatasourceSpanBuilder setFaasDocumentTime(String faasDocumentTime) { + internalBuilder.setAttribute("faas.document.time", faasDocumentTime); + return this; + } + + /** + * Sets faas.document.name. + * + * @param faasDocumentName The document name/table subjected to the operation. + *
For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the + * table name. + */ + public FaasDatasourceSpanBuilder setFaasDocumentName(String faasDocumentName) { + internalBuilder.setAttribute("faas.document.name", faasDocumentName); + return this; + } + } +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasHttpSemanticConvention.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasHttpSemanticConvention.java new file mode 100644 index 0000000000..89b994b4d2 --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasHttpSemanticConvention.java @@ -0,0 +1,229 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; + +public interface FaasHttpSemanticConvention { + void end(); + + Span getSpan(); + + /** + * Sets a value for faas.trigger + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + FaasHttpSemanticConvention setFaasTrigger(String faasTrigger); + + /** + * Sets a value for faas.execution + * + * @param faasExecution The execution id of the current function execution. + */ + FaasHttpSemanticConvention setFaasExecution(String faasExecution); + + /** + * Sets a value for http.method + * + * @param httpMethod HTTP request method. + */ + FaasHttpSemanticConvention setHttpMethod(String httpMethod); + + /** + * Sets a value for http.url + * + * @param httpUrl Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. + * Usually the fragment is not transmitted over HTTP, but if it is known, it should be + * included nevertheless. + */ + FaasHttpSemanticConvention setHttpUrl(String httpUrl); + + /** + * Sets a value for http.target + * + * @param httpTarget The full request target as passed in a HTTP request line or equivalent. + */ + FaasHttpSemanticConvention setHttpTarget(String httpTarget); + + /** + * Sets a value for http.host + * + * @param httpHost The value of the [HTTP host + * header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not + * present, this attribute should be the same. + */ + FaasHttpSemanticConvention setHttpHost(String httpHost); + + /** + * Sets a value for http.scheme + * + * @param httpScheme The URI scheme identifying the used protocol. + */ + FaasHttpSemanticConvention setHttpScheme(String httpScheme); + + /** + * Sets a value for http.status_code + * + * @param httpStatusCode [HTTP response status + * code](https://tools.ietf.org/html/rfc7231#section-6). + */ + FaasHttpSemanticConvention setHttpStatusCode(long httpStatusCode); + + /** + * Sets a value for http.status_text + * + * @param httpStatusText [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). + */ + FaasHttpSemanticConvention setHttpStatusText(String httpStatusText); + + /** + * Sets a value for http.flavor + * + * @param httpFlavor Kind of HTTP protocol used. + *
If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if + * `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. + */ + FaasHttpSemanticConvention setHttpFlavor(String httpFlavor); + + /** + * Sets a value for http.user_agent + * + * @param httpUserAgent Value of the [HTTP + * User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. + */ + FaasHttpSemanticConvention setHttpUserAgent(String httpUserAgent); + + /** + * Sets a value for http.request_content_length + * + * @param httpRequestContentLength The size of the request payload body in bytes. This is the + * number of bytes transferred excluding headers and is often, but not always, present as the + * [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests + * using transport encoding, this should be the compressed size. + */ + FaasHttpSemanticConvention setHttpRequestContentLength(long httpRequestContentLength); + + /** + * Sets a value for http.request_content_length_uncompressed + * + * @param httpRequestContentLengthUncompressed The size of the uncompressed request payload body + * after transport decoding. Not set if transport encoding not used. + */ + FaasHttpSemanticConvention setHttpRequestContentLengthUncompressed( + long httpRequestContentLengthUncompressed); + + /** + * Sets a value for http.response_content_length + * + * @param httpResponseContentLength The size of the response payload body in bytes. This is the + * number of bytes transferred excluding headers and is often, but not always, present as the + * [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests + * using transport encoding, this should be the compressed size. + */ + FaasHttpSemanticConvention setHttpResponseContentLength(long httpResponseContentLength); + + /** + * Sets a value for http.response_content_length_uncompressed + * + * @param httpResponseContentLengthUncompressed The size of the uncompressed response payload body + * after transport decoding. Not set if transport encoding not used. + */ + FaasHttpSemanticConvention setHttpResponseContentLengthUncompressed( + long httpResponseContentLengthUncompressed); + + /** + * Sets a value for http.server_name + * + * @param httpServerName The primary server name of the matched virtual host. This should be + * obtained via configuration. If no such configuration can be obtained, this attribute MUST + * NOT be set ( `net.host.name` should be used instead). + *
http.url is usually not readily available on the server side but would have to be + * assembled in a cumbersome and sometimes lossy process from other information (see e.g. + * open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data + * that is available. + */ + FaasHttpSemanticConvention setHttpServerName(String httpServerName); + + /** + * Sets a value for http.route + * + * @param httpRoute The matched route (path template). + */ + FaasHttpSemanticConvention setHttpRoute(String httpRoute); + + /** + * Sets a value for http.client_ip + * + * @param httpClientIp The IP address of the original client behind all proxies, if known (e.g. + * from + * [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). + *
This is not necessarily the same as `net.peer.ip`, which would identify the + * network-level peer, which may be a proxy. + */ + FaasHttpSemanticConvention setHttpClientIp(String httpClientIp); + + /** + * Sets a value for net.transport + * + * @param netTransport Transport protocol used. See note below. + */ + FaasHttpSemanticConvention setNetTransport(String netTransport); + + /** + * Sets a value for net.peer.ip + * + * @param netPeerIp Remote address of the peer (dotted decimal for IPv4 or + * [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). + */ + FaasHttpSemanticConvention setNetPeerIp(String netPeerIp); + + /** + * Sets a value for net.peer.port + * + * @param netPeerPort Remote port number. + */ + FaasHttpSemanticConvention setNetPeerPort(long netPeerPort); + + /** + * Sets a value for net.peer.name + * + * @param netPeerName Remote hostname or similar, see note below. + */ + FaasHttpSemanticConvention setNetPeerName(String netPeerName); + + /** + * Sets a value for net.host.ip + * + * @param netHostIp Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. + */ + FaasHttpSemanticConvention setNetHostIp(String netHostIp); + + /** + * Sets a value for net.host.port + * + * @param netHostPort Like `net.peer.port` but for the host port. + */ + FaasHttpSemanticConvention setNetHostPort(long netHostPort); + + /** + * Sets a value for net.host.name + * + * @param netHostName Local hostname or similar, see note below. + */ + FaasHttpSemanticConvention setNetHostName(String netHostName); +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasHttpSpan.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasHttpSpan.java new file mode 100644 index 0000000000..777fe439b0 --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasHttpSpan.java @@ -0,0 +1,692 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; +import io.opentelemetry.trace.SpanContext; +import io.opentelemetry.trace.Tracer; + +public class FaasHttpSpan extends DelegatingSpan implements FaasHttpSemanticConvention { + + protected FaasHttpSpan(Span span) { + super(span); + } + + /** + * Entry point to generate a {@link FaasHttpSpan}. + * + * @param tracer Tracer to use + * @param spanName Name for the {@link Span} + * @return a {@link FaasHttpSpan} object. + */ + public static FaasHttpSpanBuilder createFaasHttpSpan(Tracer tracer, String spanName) { + return new FaasHttpSpanBuilder(tracer, spanName); + } + + /** + * Creates a {@link FaasHttpSpan} from a {@link FaasSpanSpan}. + * + * @param builder {@link FaasSpanSpan.FaasSpanSpanBuilder} to use. + * @return a {@link FaasHttpSpan} object built from a {@link FaasSpanSpan}. + */ + public static FaasHttpSpanBuilder createFaasHttpSpan(FaasSpanSpan.FaasSpanSpanBuilder builder) { + // we accept a builder from FaasSpan since FaasHttp "extends" FaasSpan + return new FaasHttpSpanBuilder(builder.getSpanBuilder()); + } + + /** @return the Span used internally */ + @Override + public Span getSpan() { + return this.delegate; + } + + /** Terminates the Span. Here there is the checking for required attributes. */ + @Override + public void end() { + delegate.end(); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + @Override + public FaasHttpSemanticConvention setFaasTrigger(String faasTrigger) { + delegate.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + @Override + public FaasHttpSemanticConvention setFaasExecution(String faasExecution) { + delegate.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets http.method. + * + * @param httpMethod HTTP request method. + */ + @Override + public FaasHttpSemanticConvention setHttpMethod(String httpMethod) { + delegate.setAttribute("http.method", httpMethod); + return this; + } + + /** + * Sets http.url. + * + * @param httpUrl Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. + * Usually the fragment is not transmitted over HTTP, but if it is known, it should be + * included nevertheless. + */ + @Override + public FaasHttpSemanticConvention setHttpUrl(String httpUrl) { + delegate.setAttribute("http.url", httpUrl); + return this; + } + + /** + * Sets http.target. + * + * @param httpTarget The full request target as passed in a HTTP request line or equivalent. + */ + @Override + public FaasHttpSemanticConvention setHttpTarget(String httpTarget) { + delegate.setAttribute("http.target", httpTarget); + return this; + } + + /** + * Sets http.host. + * + * @param httpHost The value of the [HTTP host + * header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not + * present, this attribute should be the same. + */ + @Override + public FaasHttpSemanticConvention setHttpHost(String httpHost) { + delegate.setAttribute("http.host", httpHost); + return this; + } + + /** + * Sets http.scheme. + * + * @param httpScheme The URI scheme identifying the used protocol. + */ + @Override + public FaasHttpSemanticConvention setHttpScheme(String httpScheme) { + delegate.setAttribute("http.scheme", httpScheme); + return this; + } + + /** + * Sets http.status_code. + * + * @param httpStatusCode [HTTP response status + * code](https://tools.ietf.org/html/rfc7231#section-6). + */ + @Override + public FaasHttpSemanticConvention setHttpStatusCode(long httpStatusCode) { + delegate.setAttribute("http.status_code", httpStatusCode); + return this; + } + + /** + * Sets http.status_text. + * + * @param httpStatusText [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). + */ + @Override + public FaasHttpSemanticConvention setHttpStatusText(String httpStatusText) { + delegate.setAttribute("http.status_text", httpStatusText); + return this; + } + + /** + * Sets http.flavor. + * + * @param httpFlavor Kind of HTTP protocol used. + *
If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if + * `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. + */ + @Override + public FaasHttpSemanticConvention setHttpFlavor(String httpFlavor) { + delegate.setAttribute("http.flavor", httpFlavor); + return this; + } + + /** + * Sets http.user_agent. + * + * @param httpUserAgent Value of the [HTTP + * User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. + */ + @Override + public FaasHttpSemanticConvention setHttpUserAgent(String httpUserAgent) { + delegate.setAttribute("http.user_agent", httpUserAgent); + return this; + } + + /** + * Sets http.request_content_length. + * + * @param httpRequestContentLength The size of the request payload body in bytes. This is the + * number of bytes transferred excluding headers and is often, but not always, present as the + * [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests + * using transport encoding, this should be the compressed size. + */ + @Override + public FaasHttpSemanticConvention setHttpRequestContentLength(long httpRequestContentLength) { + delegate.setAttribute("http.request_content_length", httpRequestContentLength); + return this; + } + + /** + * Sets http.request_content_length_uncompressed. + * + * @param httpRequestContentLengthUncompressed The size of the uncompressed request payload body + * after transport decoding. Not set if transport encoding not used. + */ + @Override + public FaasHttpSemanticConvention setHttpRequestContentLengthUncompressed( + long httpRequestContentLengthUncompressed) { + delegate.setAttribute( + "http.request_content_length_uncompressed", httpRequestContentLengthUncompressed); + return this; + } + + /** + * Sets http.response_content_length. + * + * @param httpResponseContentLength The size of the response payload body in bytes. This is the + * number of bytes transferred excluding headers and is often, but not always, present as the + * [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests + * using transport encoding, this should be the compressed size. + */ + @Override + public FaasHttpSemanticConvention setHttpResponseContentLength(long httpResponseContentLength) { + delegate.setAttribute("http.response_content_length", httpResponseContentLength); + return this; + } + + /** + * Sets http.response_content_length_uncompressed. + * + * @param httpResponseContentLengthUncompressed The size of the uncompressed response payload body + * after transport decoding. Not set if transport encoding not used. + */ + @Override + public FaasHttpSemanticConvention setHttpResponseContentLengthUncompressed( + long httpResponseContentLengthUncompressed) { + delegate.setAttribute( + "http.response_content_length_uncompressed", httpResponseContentLengthUncompressed); + return this; + } + + /** + * Sets http.server_name. + * + * @param httpServerName The primary server name of the matched virtual host. This should be + * obtained via configuration. If no such configuration can be obtained, this attribute MUST + * NOT be set ( `net.host.name` should be used instead). + *
http.url is usually not readily available on the server side but would have to be + * assembled in a cumbersome and sometimes lossy process from other information (see e.g. + * open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data + * that is available. + */ + @Override + public FaasHttpSemanticConvention setHttpServerName(String httpServerName) { + delegate.setAttribute("http.server_name", httpServerName); + return this; + } + + /** + * Sets http.route. + * + * @param httpRoute The matched route (path template). + */ + @Override + public FaasHttpSemanticConvention setHttpRoute(String httpRoute) { + delegate.setAttribute("http.route", httpRoute); + return this; + } + + /** + * Sets http.client_ip. + * + * @param httpClientIp The IP address of the original client behind all proxies, if known (e.g. + * from + * [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). + *
This is not necessarily the same as `net.peer.ip`, which would identify the + * network-level peer, which may be a proxy. + */ + @Override + public FaasHttpSemanticConvention setHttpClientIp(String httpClientIp) { + delegate.setAttribute("http.client_ip", httpClientIp); + return this; + } + + /** + * Sets net.transport. + * + * @param netTransport Transport protocol used. See note below. + */ + @Override + public FaasHttpSemanticConvention setNetTransport(String netTransport) { + delegate.setAttribute("net.transport", netTransport); + return this; + } + + /** + * Sets net.peer.ip. + * + * @param netPeerIp Remote address of the peer (dotted decimal for IPv4 or + * [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). + */ + @Override + public FaasHttpSemanticConvention setNetPeerIp(String netPeerIp) { + delegate.setAttribute("net.peer.ip", netPeerIp); + return this; + } + + /** + * Sets net.peer.port. + * + * @param netPeerPort Remote port number. + */ + @Override + public FaasHttpSemanticConvention setNetPeerPort(long netPeerPort) { + delegate.setAttribute("net.peer.port", netPeerPort); + return this; + } + + /** + * Sets net.peer.name. + * + * @param netPeerName Remote hostname or similar, see note below. + */ + @Override + public FaasHttpSemanticConvention setNetPeerName(String netPeerName) { + delegate.setAttribute("net.peer.name", netPeerName); + return this; + } + + /** + * Sets net.host.ip. + * + * @param netHostIp Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. + */ + @Override + public FaasHttpSemanticConvention setNetHostIp(String netHostIp) { + delegate.setAttribute("net.host.ip", netHostIp); + return this; + } + + /** + * Sets net.host.port. + * + * @param netHostPort Like `net.peer.port` but for the host port. + */ + @Override + public FaasHttpSemanticConvention setNetHostPort(long netHostPort) { + delegate.setAttribute("net.host.port", netHostPort); + return this; + } + + /** + * Sets net.host.name. + * + * @param netHostName Local hostname or similar, see note below. + */ + @Override + public FaasHttpSemanticConvention setNetHostName(String netHostName) { + delegate.setAttribute("net.host.name", netHostName); + return this; + } + + /** Builder class for {@link FaasHttpSpan}. */ + public static class FaasHttpSpanBuilder { + // Protected because maybe we want to extend manually these classes + protected Span.Builder internalBuilder; + + protected FaasHttpSpanBuilder(Tracer tracer, String spanName) { + internalBuilder = tracer.spanBuilder(spanName); + } + + public FaasHttpSpanBuilder(Span.Builder spanBuilder) { + this.internalBuilder = spanBuilder; + } + + public Span.Builder getSpanBuilder() { + return this.internalBuilder; + } + + /** sets the {@link Span} parent. */ + public FaasHttpSpanBuilder setParent(Span parent) { + this.internalBuilder.setParent(parent); + return this; + } + + /** sets the {@link Span} parent. */ + public FaasHttpSpanBuilder setParent(SpanContext remoteParent) { + this.internalBuilder.setParent(remoteParent); + return this; + } + + /** this method sets the type of the {@link Span} is only available in the builder. */ + public FaasHttpSpanBuilder setKind(Span.Kind kind) { + internalBuilder.setSpanKind(kind); + return this; + } + + /** starts the span */ + public FaasHttpSpan start() { + // check for sampling relevant field here, but there are none. + return new FaasHttpSpan(this.internalBuilder.startSpan()); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + public FaasHttpSpanBuilder setFaasTrigger(String faasTrigger) { + internalBuilder.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + public FaasHttpSpanBuilder setFaasExecution(String faasExecution) { + internalBuilder.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets http.method. + * + * @param httpMethod HTTP request method. + */ + public FaasHttpSpanBuilder setHttpMethod(String httpMethod) { + internalBuilder.setAttribute("http.method", httpMethod); + return this; + } + + /** + * Sets http.url. + * + * @param httpUrl Full HTTP request URL in the form + * `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted + * over HTTP, but if it is known, it should be included nevertheless. + */ + public FaasHttpSpanBuilder setHttpUrl(String httpUrl) { + internalBuilder.setAttribute("http.url", httpUrl); + return this; + } + + /** + * Sets http.target. + * + * @param httpTarget The full request target as passed in a HTTP request line or equivalent. + */ + public FaasHttpSpanBuilder setHttpTarget(String httpTarget) { + internalBuilder.setAttribute("http.target", httpTarget); + return this; + } + + /** + * Sets http.host. + * + * @param httpHost The value of the [HTTP host + * header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not + * present, this attribute should be the same. + */ + public FaasHttpSpanBuilder setHttpHost(String httpHost) { + internalBuilder.setAttribute("http.host", httpHost); + return this; + } + + /** + * Sets http.scheme. + * + * @param httpScheme The URI scheme identifying the used protocol. + */ + public FaasHttpSpanBuilder setHttpScheme(String httpScheme) { + internalBuilder.setAttribute("http.scheme", httpScheme); + return this; + } + + /** + * Sets http.status_code. + * + * @param httpStatusCode [HTTP response status + * code](https://tools.ietf.org/html/rfc7231#section-6). + */ + public FaasHttpSpanBuilder setHttpStatusCode(long httpStatusCode) { + internalBuilder.setAttribute("http.status_code", httpStatusCode); + return this; + } + + /** + * Sets http.status_text. + * + * @param httpStatusText [HTTP reason + * phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). + */ + public FaasHttpSpanBuilder setHttpStatusText(String httpStatusText) { + internalBuilder.setAttribute("http.status_text", httpStatusText); + return this; + } + + /** + * Sets http.flavor. + * + * @param httpFlavor Kind of HTTP protocol used. + *
If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if + * `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. + */ + public FaasHttpSpanBuilder setHttpFlavor(String httpFlavor) { + internalBuilder.setAttribute("http.flavor", httpFlavor); + return this; + } + + /** + * Sets http.user_agent. + * + * @param httpUserAgent Value of the [HTTP + * User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. + */ + public FaasHttpSpanBuilder setHttpUserAgent(String httpUserAgent) { + internalBuilder.setAttribute("http.user_agent", httpUserAgent); + return this; + } + + /** + * Sets http.request_content_length. + * + * @param httpRequestContentLength The size of the request payload body in bytes. This is the + * number of bytes transferred excluding headers and is often, but not always, present as + * the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For + * requests using transport encoding, this should be the compressed size. + */ + public FaasHttpSpanBuilder setHttpRequestContentLength(long httpRequestContentLength) { + internalBuilder.setAttribute("http.request_content_length", httpRequestContentLength); + return this; + } + + /** + * Sets http.request_content_length_uncompressed. + * + * @param httpRequestContentLengthUncompressed The size of the uncompressed request payload body + * after transport decoding. Not set if transport encoding not used. + */ + public FaasHttpSpanBuilder setHttpRequestContentLengthUncompressed( + long httpRequestContentLengthUncompressed) { + internalBuilder.setAttribute( + "http.request_content_length_uncompressed", httpRequestContentLengthUncompressed); + return this; + } + + /** + * Sets http.response_content_length. + * + * @param httpResponseContentLength The size of the response payload body in bytes. This is the + * number of bytes transferred excluding headers and is often, but not always, present as + * the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For + * requests using transport encoding, this should be the compressed size. + */ + public FaasHttpSpanBuilder setHttpResponseContentLength(long httpResponseContentLength) { + internalBuilder.setAttribute("http.response_content_length", httpResponseContentLength); + return this; + } + + /** + * Sets http.response_content_length_uncompressed. + * + * @param httpResponseContentLengthUncompressed The size of the uncompressed response payload + * body after transport decoding. Not set if transport encoding not used. + */ + public FaasHttpSpanBuilder setHttpResponseContentLengthUncompressed( + long httpResponseContentLengthUncompressed) { + internalBuilder.setAttribute( + "http.response_content_length_uncompressed", httpResponseContentLengthUncompressed); + return this; + } + + /** + * Sets http.server_name. + * + * @param httpServerName The primary server name of the matched virtual host. This should be + * obtained via configuration. If no such configuration can be obtained, this attribute MUST + * NOT be set ( `net.host.name` should be used instead). + *
http.url is usually not readily available on the server side but would have to be + * assembled in a cumbersome and sometimes lossy process from other information (see e.g. + * open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw + * data that is available. + */ + public FaasHttpSpanBuilder setHttpServerName(String httpServerName) { + internalBuilder.setAttribute("http.server_name", httpServerName); + return this; + } + + /** + * Sets http.route. + * + * @param httpRoute The matched route (path template). + */ + public FaasHttpSpanBuilder setHttpRoute(String httpRoute) { + internalBuilder.setAttribute("http.route", httpRoute); + return this; + } + + /** + * Sets http.client_ip. + * + * @param httpClientIp The IP address of the original client behind all proxies, if known (e.g. + * from + * [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). + *
This is not necessarily the same as `net.peer.ip`, which would identify the + * network-level peer, which may be a proxy. + */ + public FaasHttpSpanBuilder setHttpClientIp(String httpClientIp) { + internalBuilder.setAttribute("http.client_ip", httpClientIp); + return this; + } + + /** + * Sets net.transport. + * + * @param netTransport Transport protocol used. See note below. + */ + public FaasHttpSpanBuilder setNetTransport(String netTransport) { + internalBuilder.setAttribute("net.transport", netTransport); + return this; + } + + /** + * Sets net.peer.ip. + * + * @param netPeerIp Remote address of the peer (dotted decimal for IPv4 or + * [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). + */ + public FaasHttpSpanBuilder setNetPeerIp(String netPeerIp) { + internalBuilder.setAttribute("net.peer.ip", netPeerIp); + return this; + } + + /** + * Sets net.peer.port. + * + * @param netPeerPort Remote port number. + */ + public FaasHttpSpanBuilder setNetPeerPort(long netPeerPort) { + internalBuilder.setAttribute("net.peer.port", netPeerPort); + return this; + } + + /** + * Sets net.peer.name. + * + * @param netPeerName Remote hostname or similar, see note below. + */ + public FaasHttpSpanBuilder setNetPeerName(String netPeerName) { + internalBuilder.setAttribute("net.peer.name", netPeerName); + return this; + } + + /** + * Sets net.host.ip. + * + * @param netHostIp Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. + */ + public FaasHttpSpanBuilder setNetHostIp(String netHostIp) { + internalBuilder.setAttribute("net.host.ip", netHostIp); + return this; + } + + /** + * Sets net.host.port. + * + * @param netHostPort Like `net.peer.port` but for the host port. + */ + public FaasHttpSpanBuilder setNetHostPort(long netHostPort) { + internalBuilder.setAttribute("net.host.port", netHostPort); + return this; + } + + /** + * Sets net.host.name. + * + * @param netHostName Local hostname or similar, see note below. + */ + public FaasHttpSpanBuilder setNetHostName(String netHostName) { + internalBuilder.setAttribute("net.host.name", netHostName); + return this; + } + } +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasPubsubSemanticConvention.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasPubsubSemanticConvention.java new file mode 100644 index 0000000000..17bee6a337 --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasPubsubSemanticConvention.java @@ -0,0 +1,174 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; + +public interface FaasPubsubSemanticConvention { + void end(); + + Span getSpan(); + + /** + * Sets a value for faas.trigger + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + FaasPubsubSemanticConvention setFaasTrigger(String faasTrigger); + + /** + * Sets a value for faas.execution + * + * @param faasExecution The execution id of the current function execution. + */ + FaasPubsubSemanticConvention setFaasExecution(String faasExecution); + + /** + * Sets a value for messaging.system + * + * @param messagingSystem A string identifying the messaging system. + */ + FaasPubsubSemanticConvention setMessagingSystem(String messagingSystem); + + /** + * Sets a value for messaging.destination + * + * @param messagingDestination The message destination name. This might be equal to the span name + * but is required nevertheless. + */ + FaasPubsubSemanticConvention setMessagingDestination(String messagingDestination); + + /** + * Sets a value for messaging.destination_kind + * + * @param messagingDestinationKind The kind of message destination. + */ + FaasPubsubSemanticConvention setMessagingDestinationKind(String messagingDestinationKind); + + /** + * Sets a value for messaging.temp_destination + * + * @param messagingTempDestination A boolean that is true if the message destination is temporary. + */ + FaasPubsubSemanticConvention setMessagingTempDestination(boolean messagingTempDestination); + + /** + * Sets a value for messaging.protocol + * + * @param messagingProtocol The name of the transport protocol. + */ + FaasPubsubSemanticConvention setMessagingProtocol(String messagingProtocol); + + /** + * Sets a value for messaging.protocol_version + * + * @param messagingProtocolVersion The version of the transport protocol. + */ + FaasPubsubSemanticConvention setMessagingProtocolVersion(String messagingProtocolVersion); + + /** + * Sets a value for messaging.url + * + * @param messagingUrl Connection string. + */ + FaasPubsubSemanticConvention setMessagingUrl(String messagingUrl); + + /** + * Sets a value for messaging.message_id + * + * @param messagingMessageId A value used by the messaging system as an identifier for the + * message, represented as a string. + */ + FaasPubsubSemanticConvention setMessagingMessageId(String messagingMessageId); + + /** + * Sets a value for messaging.conversation_id + * + * @param messagingConversationId A value identifying the conversation to which the message + * belongs, represented as a string. Sometimes called "Correlation ID". + */ + FaasPubsubSemanticConvention setMessagingConversationId(String messagingConversationId); + + /** + * Sets a value for messaging.message_payload_size_bytes + * + * @param messagingMessagePayloadSizeBytes The (uncompressed) size of the message payload in + * bytes. Also use this attribute if it is unknown whether the compressed or uncompressed + * payload size is reported. + */ + FaasPubsubSemanticConvention setMessagingMessagePayloadSizeBytes( + long messagingMessagePayloadSizeBytes); + + /** + * Sets a value for messaging.message_payload_compressed_size_bytes + * + * @param messagingMessagePayloadCompressedSizeBytes The compressed size of the message payload in + * bytes. + */ + FaasPubsubSemanticConvention setMessagingMessagePayloadCompressedSizeBytes( + long messagingMessagePayloadCompressedSizeBytes); + + /** + * Sets a value for net.peer.port + * + * @param netPeerPort Remote port number. + */ + FaasPubsubSemanticConvention setNetPeerPort(long netPeerPort); + + /** + * Sets a value for net.transport + * + * @param netTransport Strongly recommended for in-process queueing systems. + */ + FaasPubsubSemanticConvention setNetTransport(String netTransport); + + /** + * Sets a value for net.peer.ip + * + * @param netPeerIp Remote address of the peer (dotted decimal for IPv4 or + * [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). + */ + FaasPubsubSemanticConvention setNetPeerIp(String netPeerIp); + + /** + * Sets a value for net.peer.name + * + * @param netPeerName Remote hostname or similar, see note below. + */ + FaasPubsubSemanticConvention setNetPeerName(String netPeerName); + + /** + * Sets a value for net.host.ip + * + * @param netHostIp Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. + */ + FaasPubsubSemanticConvention setNetHostIp(String netHostIp); + + /** + * Sets a value for net.host.port + * + * @param netHostPort Like `net.peer.port` but for the host port. + */ + FaasPubsubSemanticConvention setNetHostPort(long netHostPort); + + /** + * Sets a value for net.host.name + * + * @param netHostName Local hostname or similar, see note below. + */ + FaasPubsubSemanticConvention setNetHostName(String netHostName); +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasPubsubSpan.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasPubsubSpan.java new file mode 100644 index 0000000000..eeea1a4341 --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasPubsubSpan.java @@ -0,0 +1,550 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; +import io.opentelemetry.trace.SpanContext; +import io.opentelemetry.trace.Tracer; + +public class FaasPubsubSpan extends DelegatingSpan implements FaasPubsubSemanticConvention { + + protected FaasPubsubSpan(Span span) { + super(span); + } + + /** + * Entry point to generate a {@link FaasPubsubSpan}. + * + * @param tracer Tracer to use + * @param spanName Name for the {@link Span} + * @return a {@link FaasPubsubSpan} object. + */ + public static FaasPubsubSpanBuilder createFaasPubsubSpan(Tracer tracer, String spanName) { + return new FaasPubsubSpanBuilder(tracer, spanName); + } + + /** + * Creates a {@link FaasPubsubSpan} from a {@link FaasSpanSpan}. + * + * @param builder {@link FaasSpanSpan.FaasSpanSpanBuilder} to use. + * @return a {@link FaasPubsubSpan} object built from a {@link FaasSpanSpan}. + */ + public static FaasPubsubSpanBuilder createFaasPubsubSpan( + FaasSpanSpan.FaasSpanSpanBuilder builder) { + // we accept a builder from FaasSpan since FaasPubsub "extends" FaasSpan + return new FaasPubsubSpanBuilder(builder.getSpanBuilder()); + } + + /** @return the Span used internally */ + @Override + public Span getSpan() { + return this.delegate; + } + + /** Terminates the Span. Here there is the checking for required attributes. */ + @Override + public void end() { + delegate.end(); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + @Override + public FaasPubsubSemanticConvention setFaasTrigger(String faasTrigger) { + delegate.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + @Override + public FaasPubsubSemanticConvention setFaasExecution(String faasExecution) { + delegate.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets messaging.system. + * + * @param messagingSystem A string identifying the messaging system. + */ + @Override + public FaasPubsubSemanticConvention setMessagingSystem(String messagingSystem) { + delegate.setAttribute("messaging.system", messagingSystem); + return this; + } + + /** + * Sets messaging.destination. + * + * @param messagingDestination The message destination name. This might be equal to the span name + * but is required nevertheless. + */ + @Override + public FaasPubsubSemanticConvention setMessagingDestination(String messagingDestination) { + delegate.setAttribute("messaging.destination", messagingDestination); + return this; + } + + /** + * Sets messaging.destination_kind. + * + * @param messagingDestinationKind The kind of message destination. + */ + @Override + public FaasPubsubSemanticConvention setMessagingDestinationKind(String messagingDestinationKind) { + delegate.setAttribute("messaging.destination_kind", messagingDestinationKind); + return this; + } + + /** + * Sets messaging.temp_destination. + * + * @param messagingTempDestination A boolean that is true if the message destination is temporary. + */ + @Override + public FaasPubsubSemanticConvention setMessagingTempDestination( + boolean messagingTempDestination) { + delegate.setAttribute("messaging.temp_destination", messagingTempDestination); + return this; + } + + /** + * Sets messaging.protocol. + * + * @param messagingProtocol The name of the transport protocol. + */ + @Override + public FaasPubsubSemanticConvention setMessagingProtocol(String messagingProtocol) { + delegate.setAttribute("messaging.protocol", messagingProtocol); + return this; + } + + /** + * Sets messaging.protocol_version. + * + * @param messagingProtocolVersion The version of the transport protocol. + */ + @Override + public FaasPubsubSemanticConvention setMessagingProtocolVersion(String messagingProtocolVersion) { + delegate.setAttribute("messaging.protocol_version", messagingProtocolVersion); + return this; + } + + /** + * Sets messaging.url. + * + * @param messagingUrl Connection string. + */ + @Override + public FaasPubsubSemanticConvention setMessagingUrl(String messagingUrl) { + delegate.setAttribute("messaging.url", messagingUrl); + return this; + } + + /** + * Sets messaging.message_id. + * + * @param messagingMessageId A value used by the messaging system as an identifier for the + * message, represented as a string. + */ + @Override + public FaasPubsubSemanticConvention setMessagingMessageId(String messagingMessageId) { + delegate.setAttribute("messaging.message_id", messagingMessageId); + return this; + } + + /** + * Sets messaging.conversation_id. + * + * @param messagingConversationId A value identifying the conversation to which the message + * belongs, represented as a string. Sometimes called "Correlation ID". + */ + @Override + public FaasPubsubSemanticConvention setMessagingConversationId(String messagingConversationId) { + delegate.setAttribute("messaging.conversation_id", messagingConversationId); + return this; + } + + /** + * Sets messaging.message_payload_size_bytes. + * + * @param messagingMessagePayloadSizeBytes The (uncompressed) size of the message payload in + * bytes. Also use this attribute if it is unknown whether the compressed or uncompressed + * payload size is reported. + */ + @Override + public FaasPubsubSemanticConvention setMessagingMessagePayloadSizeBytes( + long messagingMessagePayloadSizeBytes) { + delegate.setAttribute("messaging.message_payload_size_bytes", messagingMessagePayloadSizeBytes); + return this; + } + + /** + * Sets messaging.message_payload_compressed_size_bytes. + * + * @param messagingMessagePayloadCompressedSizeBytes The compressed size of the message payload in + * bytes. + */ + @Override + public FaasPubsubSemanticConvention setMessagingMessagePayloadCompressedSizeBytes( + long messagingMessagePayloadCompressedSizeBytes) { + delegate.setAttribute( + "messaging.message_payload_compressed_size_bytes", + messagingMessagePayloadCompressedSizeBytes); + return this; + } + + /** + * Sets net.peer.port. + * + * @param netPeerPort Remote port number. + */ + @Override + public FaasPubsubSemanticConvention setNetPeerPort(long netPeerPort) { + delegate.setAttribute("net.peer.port", netPeerPort); + return this; + } + + /** + * Sets net.transport. + * + * @param netTransport Strongly recommended for in-process queueing systems. + */ + @Override + public FaasPubsubSemanticConvention setNetTransport(String netTransport) { + delegate.setAttribute("net.transport", netTransport); + return this; + } + + /** + * Sets net.peer.ip. + * + * @param netPeerIp Remote address of the peer (dotted decimal for IPv4 or + * [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). + */ + @Override + public FaasPubsubSemanticConvention setNetPeerIp(String netPeerIp) { + delegate.setAttribute("net.peer.ip", netPeerIp); + return this; + } + + /** + * Sets net.peer.name. + * + * @param netPeerName Remote hostname or similar, see note below. + */ + @Override + public FaasPubsubSemanticConvention setNetPeerName(String netPeerName) { + delegate.setAttribute("net.peer.name", netPeerName); + return this; + } + + /** + * Sets net.host.ip. + * + * @param netHostIp Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. + */ + @Override + public FaasPubsubSemanticConvention setNetHostIp(String netHostIp) { + delegate.setAttribute("net.host.ip", netHostIp); + return this; + } + + /** + * Sets net.host.port. + * + * @param netHostPort Like `net.peer.port` but for the host port. + */ + @Override + public FaasPubsubSemanticConvention setNetHostPort(long netHostPort) { + delegate.setAttribute("net.host.port", netHostPort); + return this; + } + + /** + * Sets net.host.name. + * + * @param netHostName Local hostname or similar, see note below. + */ + @Override + public FaasPubsubSemanticConvention setNetHostName(String netHostName) { + delegate.setAttribute("net.host.name", netHostName); + return this; + } + + /** Builder class for {@link FaasPubsubSpan}. */ + public static class FaasPubsubSpanBuilder { + // Protected because maybe we want to extend manually these classes + protected Span.Builder internalBuilder; + + protected FaasPubsubSpanBuilder(Tracer tracer, String spanName) { + internalBuilder = tracer.spanBuilder(spanName); + } + + public FaasPubsubSpanBuilder(Span.Builder spanBuilder) { + this.internalBuilder = spanBuilder; + } + + public Span.Builder getSpanBuilder() { + return this.internalBuilder; + } + + /** sets the {@link Span} parent. */ + public FaasPubsubSpanBuilder setParent(Span parent) { + this.internalBuilder.setParent(parent); + return this; + } + + /** sets the {@link Span} parent. */ + public FaasPubsubSpanBuilder setParent(SpanContext remoteParent) { + this.internalBuilder.setParent(remoteParent); + return this; + } + + /** this method sets the type of the {@link Span} is only available in the builder. */ + public FaasPubsubSpanBuilder setKind(Span.Kind kind) { + internalBuilder.setSpanKind(kind); + return this; + } + + /** starts the span */ + public FaasPubsubSpan start() { + // check for sampling relevant field here, but there are none. + return new FaasPubsubSpan(this.internalBuilder.startSpan()); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + public FaasPubsubSpanBuilder setFaasTrigger(String faasTrigger) { + internalBuilder.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + public FaasPubsubSpanBuilder setFaasExecution(String faasExecution) { + internalBuilder.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets messaging.system. + * + * @param messagingSystem A string identifying the messaging system. + */ + public FaasPubsubSpanBuilder setMessagingSystem(String messagingSystem) { + internalBuilder.setAttribute("messaging.system", messagingSystem); + return this; + } + + /** + * Sets messaging.destination. + * + * @param messagingDestination The message destination name. This might be equal to the span + * name but is required nevertheless. + */ + public FaasPubsubSpanBuilder setMessagingDestination(String messagingDestination) { + internalBuilder.setAttribute("messaging.destination", messagingDestination); + return this; + } + + /** + * Sets messaging.destination_kind. + * + * @param messagingDestinationKind The kind of message destination. + */ + public FaasPubsubSpanBuilder setMessagingDestinationKind(String messagingDestinationKind) { + internalBuilder.setAttribute("messaging.destination_kind", messagingDestinationKind); + return this; + } + + /** + * Sets messaging.temp_destination. + * + * @param messagingTempDestination A boolean that is true if the message destination is + * temporary. + */ + public FaasPubsubSpanBuilder setMessagingTempDestination(boolean messagingTempDestination) { + internalBuilder.setAttribute("messaging.temp_destination", messagingTempDestination); + return this; + } + + /** + * Sets messaging.protocol. + * + * @param messagingProtocol The name of the transport protocol. + */ + public FaasPubsubSpanBuilder setMessagingProtocol(String messagingProtocol) { + internalBuilder.setAttribute("messaging.protocol", messagingProtocol); + return this; + } + + /** + * Sets messaging.protocol_version. + * + * @param messagingProtocolVersion The version of the transport protocol. + */ + public FaasPubsubSpanBuilder setMessagingProtocolVersion(String messagingProtocolVersion) { + internalBuilder.setAttribute("messaging.protocol_version", messagingProtocolVersion); + return this; + } + + /** + * Sets messaging.url. + * + * @param messagingUrl Connection string. + */ + public FaasPubsubSpanBuilder setMessagingUrl(String messagingUrl) { + internalBuilder.setAttribute("messaging.url", messagingUrl); + return this; + } + + /** + * Sets messaging.message_id. + * + * @param messagingMessageId A value used by the messaging system as an identifier for the + * message, represented as a string. + */ + public FaasPubsubSpanBuilder setMessagingMessageId(String messagingMessageId) { + internalBuilder.setAttribute("messaging.message_id", messagingMessageId); + return this; + } + + /** + * Sets messaging.conversation_id. + * + * @param messagingConversationId A value identifying the conversation to which the message + * belongs, represented as a string. Sometimes called "Correlation ID". + */ + public FaasPubsubSpanBuilder setMessagingConversationId(String messagingConversationId) { + internalBuilder.setAttribute("messaging.conversation_id", messagingConversationId); + return this; + } + + /** + * Sets messaging.message_payload_size_bytes. + * + * @param messagingMessagePayloadSizeBytes The (uncompressed) size of the message payload in + * bytes. Also use this attribute if it is unknown whether the compressed or uncompressed + * payload size is reported. + */ + public FaasPubsubSpanBuilder setMessagingMessagePayloadSizeBytes( + long messagingMessagePayloadSizeBytes) { + internalBuilder.setAttribute( + "messaging.message_payload_size_bytes", messagingMessagePayloadSizeBytes); + return this; + } + + /** + * Sets messaging.message_payload_compressed_size_bytes. + * + * @param messagingMessagePayloadCompressedSizeBytes The compressed size of the message payload + * in bytes. + */ + public FaasPubsubSpanBuilder setMessagingMessagePayloadCompressedSizeBytes( + long messagingMessagePayloadCompressedSizeBytes) { + internalBuilder.setAttribute( + "messaging.message_payload_compressed_size_bytes", + messagingMessagePayloadCompressedSizeBytes); + return this; + } + + /** + * Sets net.peer.port. + * + * @param netPeerPort Remote port number. + */ + public FaasPubsubSpanBuilder setNetPeerPort(long netPeerPort) { + internalBuilder.setAttribute("net.peer.port", netPeerPort); + return this; + } + + /** + * Sets net.transport. + * + * @param netTransport Strongly recommended for in-process queueing systems. + */ + public FaasPubsubSpanBuilder setNetTransport(String netTransport) { + internalBuilder.setAttribute("net.transport", netTransport); + return this; + } + + /** + * Sets net.peer.ip. + * + * @param netPeerIp Remote address of the peer (dotted decimal for IPv4 or + * [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). + */ + public FaasPubsubSpanBuilder setNetPeerIp(String netPeerIp) { + internalBuilder.setAttribute("net.peer.ip", netPeerIp); + return this; + } + + /** + * Sets net.peer.name. + * + * @param netPeerName Remote hostname or similar, see note below. + */ + public FaasPubsubSpanBuilder setNetPeerName(String netPeerName) { + internalBuilder.setAttribute("net.peer.name", netPeerName); + return this; + } + + /** + * Sets net.host.ip. + * + * @param netHostIp Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. + */ + public FaasPubsubSpanBuilder setNetHostIp(String netHostIp) { + internalBuilder.setAttribute("net.host.ip", netHostIp); + return this; + } + + /** + * Sets net.host.port. + * + * @param netHostPort Like `net.peer.port` but for the host port. + */ + public FaasPubsubSpanBuilder setNetHostPort(long netHostPort) { + internalBuilder.setAttribute("net.host.port", netHostPort); + return this; + } + + /** + * Sets net.host.name. + * + * @param netHostName Local hostname or similar, see note below. + */ + public FaasPubsubSpanBuilder setNetHostName(String netHostName) { + internalBuilder.setAttribute("net.host.name", netHostName); + return this; + } + } +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasSpanSemanticConvention.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasSpanSemanticConvention.java new file mode 100644 index 0000000000..a4f6e8bc4b --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasSpanSemanticConvention.java @@ -0,0 +1,39 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; + +public interface FaasSpanSemanticConvention { + void end(); + + Span getSpan(); + + /** + * Sets a value for faas.trigger + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + FaasSpanSemanticConvention setFaasTrigger(String faasTrigger); + + /** + * Sets a value for faas.execution + * + * @param faasExecution The execution id of the current function execution. + */ + FaasSpanSemanticConvention setFaasExecution(String faasExecution); +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasSpanSpan.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasSpanSpan.java new file mode 100644 index 0000000000..f4a2a6a1c3 --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasSpanSpan.java @@ -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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; +import io.opentelemetry.trace.SpanContext; +import io.opentelemetry.trace.Tracer; + +public class FaasSpanSpan extends DelegatingSpan implements FaasSpanSemanticConvention { + + protected FaasSpanSpan(Span span) { + super(span); + } + + /** + * Entry point to generate a {@link FaasSpanSpan}. + * + * @param tracer Tracer to use + * @param spanName Name for the {@link Span} + * @return a {@link FaasSpanSpan} object. + */ + public static FaasSpanSpanBuilder createFaasSpanSpan(Tracer tracer, String spanName) { + return new FaasSpanSpanBuilder(tracer, spanName); + } + + /** @return the Span used internally */ + @Override + public Span getSpan() { + return this.delegate; + } + + /** Terminates the Span. Here there is the checking for required attributes. */ + @Override + public void end() { + delegate.end(); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + @Override + public FaasSpanSemanticConvention setFaasTrigger(String faasTrigger) { + delegate.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + @Override + public FaasSpanSemanticConvention setFaasExecution(String faasExecution) { + delegate.setAttribute("faas.execution", faasExecution); + return this; + } + + /** Builder class for {@link FaasSpanSpan}. */ + public static class FaasSpanSpanBuilder { + // Protected because maybe we want to extend manually these classes + protected Span.Builder internalBuilder; + + protected FaasSpanSpanBuilder(Tracer tracer, String spanName) { + internalBuilder = tracer.spanBuilder(spanName); + } + + public FaasSpanSpanBuilder(Span.Builder spanBuilder) { + this.internalBuilder = spanBuilder; + } + + public Span.Builder getSpanBuilder() { + return this.internalBuilder; + } + + /** sets the {@link Span} parent. */ + public FaasSpanSpanBuilder setParent(Span parent) { + this.internalBuilder.setParent(parent); + return this; + } + + /** sets the {@link Span} parent. */ + public FaasSpanSpanBuilder setParent(SpanContext remoteParent) { + this.internalBuilder.setParent(remoteParent); + return this; + } + + /** this method sets the type of the {@link Span} is only available in the builder. */ + public FaasSpanSpanBuilder setKind(Span.Kind kind) { + internalBuilder.setSpanKind(kind); + return this; + } + + /** starts the span */ + public FaasSpanSpan start() { + // check for sampling relevant field here, but there are none. + return new FaasSpanSpan(this.internalBuilder.startSpan()); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + public FaasSpanSpanBuilder setFaasTrigger(String faasTrigger) { + internalBuilder.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + public FaasSpanSpanBuilder setFaasExecution(String faasExecution) { + internalBuilder.setAttribute("faas.execution", faasExecution); + return this; + } + } +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasTimerSemanticConvention.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasTimerSemanticConvention.java new file mode 100644 index 0000000000..7d1969ef9f --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasTimerSemanticConvention.java @@ -0,0 +1,56 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; + +public interface FaasTimerSemanticConvention { + void end(); + + Span getSpan(); + + /** + * Sets a value for faas.trigger + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + FaasTimerSemanticConvention setFaasTrigger(String faasTrigger); + + /** + * Sets a value for faas.execution + * + * @param faasExecution The execution id of the current function execution. + */ + FaasTimerSemanticConvention setFaasExecution(String faasExecution); + + /** + * Sets a value for faas.time + * + * @param faasTime A string containing the function invocation time in the [ISO + * 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in + * [UTC](https://www.w3.org/TR/NOTE-datetime). + */ + FaasTimerSemanticConvention setFaasTime(String faasTime); + + /** + * Sets a value for faas.cron + * + * @param faasCron A string containing the schedule period as [Cron + * Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). + */ + FaasTimerSemanticConvention setFaasCron(String faasCron); +} diff --git a/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasTimerSpan.java b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasTimerSpan.java new file mode 100644 index 0000000000..e3729724aa --- /dev/null +++ b/agent-bootstrap/src/main/java/io/opentelemetry/auto/typedspan/FaasTimerSpan.java @@ -0,0 +1,194 @@ +/* + * 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 io.opentelemetry.auto.typedspan; + +import io.opentelemetry.trace.Span; +import io.opentelemetry.trace.SpanContext; +import io.opentelemetry.trace.Tracer; + +public class FaasTimerSpan extends DelegatingSpan implements FaasTimerSemanticConvention { + + protected FaasTimerSpan(Span span) { + super(span); + } + + /** + * Entry point to generate a {@link FaasTimerSpan}. + * + * @param tracer Tracer to use + * @param spanName Name for the {@link Span} + * @return a {@link FaasTimerSpan} object. + */ + public static FaasTimerSpanBuilder createFaasTimerSpan(Tracer tracer, String spanName) { + return new FaasTimerSpanBuilder(tracer, spanName); + } + + /** + * Creates a {@link FaasTimerSpan} from a {@link FaasSpanSpan}. + * + * @param builder {@link FaasSpanSpan.FaasSpanSpanBuilder} to use. + * @return a {@link FaasTimerSpan} object built from a {@link FaasSpanSpan}. + */ + public static FaasTimerSpanBuilder createFaasTimerSpan(FaasSpanSpan.FaasSpanSpanBuilder builder) { + // we accept a builder from FaasSpan since FaasTimer "extends" FaasSpan + return new FaasTimerSpanBuilder(builder.getSpanBuilder()); + } + + /** @return the Span used internally */ + @Override + public Span getSpan() { + return this.delegate; + } + + /** Terminates the Span. Here there is the checking for required attributes. */ + @Override + public void end() { + delegate.end(); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + @Override + public FaasTimerSemanticConvention setFaasTrigger(String faasTrigger) { + delegate.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + @Override + public FaasTimerSemanticConvention setFaasExecution(String faasExecution) { + delegate.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets faas.time. + * + * @param faasTime A string containing the function invocation time in the [ISO + * 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in + * [UTC](https://www.w3.org/TR/NOTE-datetime). + */ + @Override + public FaasTimerSemanticConvention setFaasTime(String faasTime) { + delegate.setAttribute("faas.time", faasTime); + return this; + } + + /** + * Sets faas.cron. + * + * @param faasCron A string containing the schedule period as [Cron + * Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). + */ + @Override + public FaasTimerSemanticConvention setFaasCron(String faasCron) { + delegate.setAttribute("faas.cron", faasCron); + return this; + } + + /** Builder class for {@link FaasTimerSpan}. */ + public static class FaasTimerSpanBuilder { + // Protected because maybe we want to extend manually these classes + protected Span.Builder internalBuilder; + + protected FaasTimerSpanBuilder(Tracer tracer, String spanName) { + internalBuilder = tracer.spanBuilder(spanName); + } + + public FaasTimerSpanBuilder(Span.Builder spanBuilder) { + this.internalBuilder = spanBuilder; + } + + public Span.Builder getSpanBuilder() { + return this.internalBuilder; + } + + /** sets the {@link Span} parent. */ + public FaasTimerSpanBuilder setParent(Span parent) { + this.internalBuilder.setParent(parent); + return this; + } + + /** sets the {@link Span} parent. */ + public FaasTimerSpanBuilder setParent(SpanContext remoteParent) { + this.internalBuilder.setParent(remoteParent); + return this; + } + + /** this method sets the type of the {@link Span} is only available in the builder. */ + public FaasTimerSpanBuilder setKind(Span.Kind kind) { + internalBuilder.setSpanKind(kind); + return this; + } + + /** starts the span */ + public FaasTimerSpan start() { + // check for sampling relevant field here, but there are none. + return new FaasTimerSpan(this.internalBuilder.startSpan()); + } + + /** + * Sets faas.trigger. + * + * @param faasTrigger Type of the trigger on which the function is executed. + */ + public FaasTimerSpanBuilder setFaasTrigger(String faasTrigger) { + internalBuilder.setAttribute("faas.trigger", faasTrigger); + return this; + } + + /** + * Sets faas.execution. + * + * @param faasExecution The execution id of the current function execution. + */ + public FaasTimerSpanBuilder setFaasExecution(String faasExecution) { + internalBuilder.setAttribute("faas.execution", faasExecution); + return this; + } + + /** + * Sets faas.time. + * + * @param faasTime A string containing the function invocation time in the [ISO + * 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in + * [UTC](https://www.w3.org/TR/NOTE-datetime). + */ + public FaasTimerSpanBuilder setFaasTime(String faasTime) { + internalBuilder.setAttribute("faas.time", faasTime); + return this; + } + + /** + * Sets faas.cron. + * + * @param faasCron A string containing the schedule period as [Cron + * Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). + */ + public FaasTimerSpanBuilder setFaasCron(String faasCron) { + internalBuilder.setAttribute("faas.cron", faasCron); + return this; + } + } +}