Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update semantic and resource attributes for spec v0.15.0 #4938

Merged
merged 3 commits into from Nov 12, 2022
Merged

Update semantic and resource attributes for spec v0.15.0 #4938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cc95b7d
Update semantic and resource attributes for spec v0.15.0
jkwatson Nov 11, 2022
e5e3cc6
explicitly exclude resource attributes
jkwatson Nov 11, 2022
72c1b76
remove more resources, include deprecated tags and attributes
jkwatson Nov 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 4 additions & 2 deletions buildscripts/semantic-convention/generate.sh
View file
Open in desktop
Expand Up @@ -4,7 +4,7 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
ROOT_DIR="${SCRIPT_DIR}/../../"

# freeze the spec & generator tools versions to make SemanticAttributes generation reproducible
SEMCONV_VERSION=1.13.0
SEMCONV_VERSION=1.15.0
SPEC_VERSION=v$SEMCONV_VERSION
SCHEMA_URL=https://opentelemetry.io/schemas/$SEMCONV_VERSION
GENERATOR_VERSION=0.14.0
Expand All @@ -22,13 +22,15 @@ git reset --hard FETCH_HEAD
cd ${SCRIPT_DIR}

docker run --rm \
-v ${SCRIPT_DIR}/opentelemetry-specification/semantic_conventions/trace:/source \
-v ${SCRIPT_DIR}/opentelemetry-specification/semantic_conventions:/source \
-v ${SCRIPT_DIR}/templates:/templates \
-v ${ROOT_DIR}/semconv/src/main/java/io/opentelemetry/semconv/trace/attributes/:/output \
otel/semconvgen:$GENERATOR_VERSION \
--exclude resource/** \
-f /source code \
--template /templates/SemanticAttributes.java.j2 \
--output /output/SemanticAttributes.java \
-Dsemconv=trace \
-Dclass=SemanticAttributes \
-DschemaUrl=$SCHEMA_URL \
-Dpkg=io.opentelemetry.semconv.trace.attributes
Expand Down
14 changes: 11 additions & 3 deletions buildscripts/semantic-convention/templates/SemanticAttributes.java.j2
View file
Open in desktop
Expand Up @@ -56,6 +56,7 @@ import io.opentelemetry.api.common.AttributeKey;
import java.util.List;

// DO NOT EDIT, this is an Auto-generated file from buildscripts/semantic-convention{{template}}
@SuppressWarnings("unused")
public final class {{class}} {
/**
* The URL of the OpenTelemetry schema for these keys and values.
Expand All @@ -70,12 +71,12 @@ public final class {{class}} {
* <p>Notes:
<ul> {{attribute.note | render_markdown(code="{{@code {0}}}", paragraph="<li>{0}</li>", list="{0}")}} </ul>
{%- endif %}
{%- if attribute.deprecated %}
{%- if (attribute.stability | string()) == "StabilityLevel.DEPRECATED" %}
*
* @deprecated {{attribute.deprecated | to_doc_brief}}.
* @deprecated {{attribute.brief | to_doc_brief}}.
{%- endif %}
*/
{%- if attribute.deprecated %}
{%- if (attribute.stability | string()) == "StabilityLevel.DEPRECATED" %}
@Deprecated
{%- endif %}
public static final AttributeKey<{{upFirst(to_java_return_type(attribute.attr_type | string))}}> {{attribute.fqn | to_const_name}} = {{to_java_key_type(attribute.attr_type | string)}}("{{attribute.fqn}}");
Expand Down Expand Up @@ -177,6 +178,13 @@ public final class {{class}} {
@Deprecated
public static final AttributeKey<String> NET_HOST_IP = stringKey("net.host.ip");

/**
* The ordinal number of request re-sending attempt.
* @deprecated This item has been removed as of 1.15.0 of the semantic conventions. Use {@link SemanticAttributes#HTTP_RESEND_COUNT} instead.
*/
@Deprecated
public static final AttributeKey<Long> HTTP_RETRY_COUNT = longKey("http.retry_count");

{% endif %}

private {{class}}() {}
Expand Down
42 changes: 34 additions & 8 deletions semconv/src/main/java/io/opentelemetry/semconv/resource/attributes/ResourceAttributes.java
View file
Open in desktop
Expand Up @@ -5,6 +5,7 @@

package io.opentelemetry.semconv.resource.attributes;

import static io.opentelemetry.api.common.AttributeKey.booleanKey;
import static io.opentelemetry.api.common.AttributeKey.longKey;
import static io.opentelemetry.api.common.AttributeKey.stringArrayKey;
import static io.opentelemetry.api.common.AttributeKey.stringKey;
Expand All @@ -14,9 +15,10 @@

// DO NOT EDIT, this is an Auto-generated file from
// buildscripts/semantic-convention/templates/SemanticAttributes.java.j2
@SuppressWarnings("unused")
public final class ResourceAttributes {
/** The URL of the OpenTelemetry schema for these keys and values. */
public static final String SCHEMA_URL = "https://opentelemetry.io/schemas/1.13.0";
public static final String SCHEMA_URL = "https://opentelemetry.io/schemas/1.15.0";

/**
* Array of brand name and version separated by a space
Expand All @@ -25,8 +27,8 @@ public final class ResourceAttributes {
*
* <ul>
* <li>This value is intended to be taken from the <a
* href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a>
* (navigator.userAgentData.brands).
* href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a> ({@code
* navigator.userAgentData.brands}).
* </ul>
*/
public static final AttributeKey<List<String>> BROWSER_BRANDS = stringArrayKey("browser.brands");
Expand All @@ -38,19 +40,32 @@ public final class ResourceAttributes {
*
* <ul>
* <li>This value is intended to be taken from the <a
* href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a>
* (navigator.userAgentData.platform). If unavailable, the legacy {@code navigator.platform}
* href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a> ({@code
* navigator.userAgentData.platform}). If unavailable, the legacy {@code navigator.platform}
* API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the
* values to be consistent. The list of possible values is defined in the <a
* href="https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform">W3C User-Agent Client
* Hints specification</a>. Note that some (but not all) of these values can overlap with
* values in the <a href="./os.md">os.type and os.name attributes</a>. However, for
* consistency, the values in the {@code browser.platform} attribute should capture the
* exact value that the user agent provides.
* values in the <a href="./os.md">{@code os.type} and {@code os.name} attributes</a>.
* However, for consistency, the values in the {@code browser.platform} attribute should
* capture the exact value that the user agent provides.
* </ul>
*/
public static final AttributeKey<String> BROWSER_PLATFORM = stringKey("browser.platform");

/**
* A boolean that is true if the browser is running on a mobile device
*
* <p>Notes:
*
* <ul>
* <li>This value is intended to be taken from the <a
* href="https://wicg.github.io/ua-client-hints/#interface">UA client hints API</a> ({@code
* navigator.userAgentData.mobile}). If unavailable, this attribute SHOULD be left unset.
* </ul>
*/
public static final AttributeKey<Boolean> BROWSER_MOBILE = booleanKey("browser.mobile");

/**
* Full user-agent string provided by the browser
*
Expand All @@ -64,6 +79,17 @@ public final class ResourceAttributes {
*/
public static final AttributeKey<String> BROWSER_USER_AGENT = stringKey("browser.user_agent");

/**
* Preferred language of the user using the browser
*
* <p>Notes:
*
* <ul>
* <li>This value is intended to be taken from the Navigator API {@code navigator.language}.
* </ul>
*/
public static final AttributeKey<String> BROWSER_LANGUAGE = stringKey("browser.language");

/** Name of the cloud provider. */
public static final AttributeKey<String> CLOUD_PROVIDER = stringKey("cloud.provider");

Expand Down
182 changes: 145 additions & 37 deletions semconv/src/main/java/io/opentelemetry/semconv/trace/attributes/SemanticAttributes.java
View file
Open in desktop
Expand Up @@ -16,9 +16,64 @@

// DO NOT EDIT, this is an Auto-generated file from
// buildscripts/semantic-convention/templates/SemanticAttributes.java.j2
@SuppressWarnings("unused")
public final class SemanticAttributes {
/** The URL of the OpenTelemetry schema for these keys and values. */
public static final String SCHEMA_URL = "https://opentelemetry.io/schemas/1.13.0";
public static final String SCHEMA_URL = "https://opentelemetry.io/schemas/1.15.0";

/**
* The type of the exception (its fully-qualified class name, if applicable). The dynamic type of
* the exception should be preferred over the static type in languages that support it.
*/
public static final AttributeKey<String> EXCEPTION_TYPE = stringKey("exception.type");

/** The exception message. */
public static final AttributeKey<String> EXCEPTION_MESSAGE = stringKey("exception.message");

/**
* A stacktrace as a string in the natural representation for the language runtime. The
* representation is to be determined and documented by each language SIG.
*/
public static final AttributeKey<String> EXCEPTION_STACKTRACE = stringKey("exception.stacktrace");

/** The name identifies the event. */
public static final AttributeKey<String> EVENT_NAME = stringKey("event.name");
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm starting to wonder if maybe we should split the files out by type...i.e. event/span/metric

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe... the counter argument is that attributes may overlap between signals and are expected to have the same semantics. I.e. MetricAttributes.HTTP_METHOD, SpanAttributes.HTTP_METHOD.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if we could annotate the attributes with some kind of indication on which signals they should be used with?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

something to think about. I don't want to jump in any direction until things stabilize a bit more, though


/**
* The domain identifies the context in which an event happened. An event name is unique only
* within a domain.
*
* <p>Notes:
*
* <ul>
* <li>An {@code event.name} is supposed to be unique only in the context of an {@code
* event.domain}, so this allows for two events in different domains to have same {@code
* event.name}, yet be unrelated events.
* </ul>
*/
public static final AttributeKey<String> EVENT_DOMAIN = stringKey("event.domain");

/** The name of the instrumentation scope - ({@code InstrumentationScope.Name} in OTLP). */
public static final AttributeKey<String> OTEL_SCOPE_NAME = stringKey("otel.scope.name");

/** The version of the instrumentation scope - ({@code InstrumentationScope.Version} in OTLP). */
public static final AttributeKey<String> OTEL_SCOPE_VERSION = stringKey("otel.scope.version");

/**
* Deprecated, use the {@code otel.scope.name} attribute.
*
* @deprecated Deprecated, use the `otel.scope.name` attribute.
*/
@Deprecated
public static final AttributeKey<String> OTEL_LIBRARY_NAME = stringKey("otel.library.name");

/**
* Deprecated, use the {@code otel.scope.version} attribute.
*
* @deprecated Deprecated, use the `otel.scope.version` attribute.
*/
@Deprecated
public static final AttributeKey<String> OTEL_LIBRARY_VERSION = stringKey("otel.library.version");

/**
* The full invoked ARN as provided on the {@code Context} passed to the function ({@code
Expand Down Expand Up @@ -237,42 +292,14 @@ public final class SemanticAttributes {
public static final AttributeKey<String> DB_SQL_TABLE = stringKey("db.sql.table");

/**
* The type of the exception (its fully-qualified class name, if applicable). The dynamic type of
* the exception should be preferred over the static type in languages that support it.
* Name of the code, either &quot;OK&quot; or &quot;ERROR&quot;. MUST NOT be set if the status
* code is UNSET.
*/
public static final AttributeKey<String> EXCEPTION_TYPE = stringKey("exception.type");

/** The exception message. */
public static final AttributeKey<String> EXCEPTION_MESSAGE = stringKey("exception.message");
public static final AttributeKey<String> OTEL_STATUS_CODE = stringKey("otel.status_code");

/**
* A stacktrace as a string in the natural representation for the language runtime. The
* representation is to be determined and documented by each language SIG.
*/
public static final AttributeKey<String> EXCEPTION_STACKTRACE = stringKey("exception.stacktrace");

/**
* SHOULD be set to true if the exception event is recorded at a point where it is known that the
* exception is escaping the scope of the span.
*
* <p>Notes:
*
* <ul>
* <li>An exception is considered to have escaped (or left) the scope of a span, if that span is
* ended while the exception is still logically &quot;in flight&quot;. This may be actually
* &quot;in flight&quot; in some languages (e.g. if the exception is passed to a Context
* manager's {@code __exit__} method in Python) but will usually be caught at the point of
* recording the exception in most languages.
* <li>It is usually not possible to determine at the point where an exception is thrown whether
* it will escape the scope of a span. However, it is trivial to know that an exception will
* escape, if one checks for an active exception just before ending the span, as done in the
* <a href="#recording-an-exception">example above</a>.
* <li>It follows that an exception may still escape the scope of the span even if the {@code
* exception.escaped} attribute was not set or set to false, since the event might have been
* recorded at a time where it was not clear whether the exception will escape.
* </ul>
*/
public static final AttributeKey<Boolean> EXCEPTION_ESCAPED = booleanKey("exception.escaped");
/** Description of the Status if it has a value, otherwise not set. */
public static final AttributeKey<String> OTEL_STATUS_DESCRIPTION =
stringKey("otel.status_description");

/**
* Type of the trigger which caused this function execution.
Expand Down Expand Up @@ -579,8 +606,18 @@ public final class SemanticAttributes {
*/
public static final AttributeKey<String> HTTP_URL = stringKey("http.url");

/** The ordinal number of request re-sending attempt. */
public static final AttributeKey<Long> HTTP_RETRY_COUNT = longKey("http.retry_count");
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
/**
* The ordinal number of request resending attempt (for any reason, including redirects).
*
* <p>Notes:
*
* <ul>
* <li>The resend count SHOULD be updated each time an HTTP request gets resent by the client,
* regardless of what was the cause of the resending (e.g. redirection, authorization
* failure, 503 Server Unavailable, network issues, or any other).
* </ul>
*/
public static final AttributeKey<Long> HTTP_RESEND_COUNT = longKey("http.resend_count");

/** The URI scheme identifying the used protocol. */
public static final AttributeKey<String> HTTP_SCHEME = stringKey("http.scheme");
Expand Down Expand Up @@ -849,6 +886,23 @@ public final class SemanticAttributes {
public static final AttributeKey<String> MESSAGING_ROCKETMQ_CLIENT_ID =
stringKey("messaging.rocketmq.client_id");

/**
* The timestamp in milliseconds that the delay message is expected to be delivered to consumer.
*/
public static final AttributeKey<Long> MESSAGING_ROCKETMQ_DELIVERY_TIMESTAMP =
longKey("messaging.rocketmq.delivery_timestamp");

/** The delay time level for delay message, which determines the message delay time. */
public static final AttributeKey<Long> MESSAGING_ROCKETMQ_DELAY_TIME_LEVEL =
longKey("messaging.rocketmq.delay_time_level");

/**
* It is essential for FIFO message. Messages that belong to the same message group are always
* processed one by one within the same consumer group.
*/
public static final AttributeKey<String> MESSAGING_ROCKETMQ_MESSAGE_GROUP =
stringKey("messaging.rocketmq.message_group");

/** Type of message. */
public static final AttributeKey<String> MESSAGING_ROCKETMQ_MESSAGE_TYPE =
stringKey("messaging.rocketmq.message_type");
Expand Down Expand Up @@ -949,7 +1003,41 @@ public final class SemanticAttributes {
public static final AttributeKey<Long> MESSAGE_UNCOMPRESSED_SIZE =
longKey("message.uncompressed_size");

/**
* SHOULD be set to true if the exception event is recorded at a point where it is known that the
* exception is escaping the scope of the span.
*
* <p>Notes:
*
* <ul>
* <li>An exception is considered to have escaped (or left) the scope of a span, if that span is
* ended while the exception is still logically &quot;in flight&quot;. This may be actually
* &quot;in flight&quot; in some languages (e.g. if the exception is passed to a Context
* manager's {@code __exit__} method in Python) but will usually be caught at the point of
* recording the exception in most languages.
* <li>It is usually not possible to determine at the point where an exception is thrown whether
* it will escape the scope of a span. However, it is trivial to know that an exception will
* escape, if one checks for an active exception just before ending the span, as done in the
* <a href="#recording-an-exception">example above</a>.
* <li>It follows that an exception may still escape the scope of the span even if the {@code
* exception.escaped} attribute was not set or set to false, since the event might have been
* recorded at a time where it was not clear whether the exception will escape.
* </ul>
*/
public static final AttributeKey<Boolean> EXCEPTION_ESCAPED = booleanKey("exception.escaped");

// Enum definitions
public static final class EventDomainValues {
/** Events from browser apps. */
public static final String BROWSER = "browser";
/** Events from mobile apps. */
public static final String DEVICE = "device";
/** Events from Kubernetes. */
public static final String K8S = "k8s";

private EventDomainValues() {}
}

public static final class OpentracingRefTypeValues {
/** The parent Span depends on the child Span in some capacity. */
public static final String CHILD_OF = "child_of";
Expand Down Expand Up @@ -1087,6 +1175,18 @@ public static final class DbCassandraConsistencyLevelValues {
private DbCassandraConsistencyLevelValues() {}
}

public static final class OtelStatusCodeValues {
/**
* The operation has been validated by an Application developer or Operator to have completed
* successfully.
*/
public static final String OK = "OK";
/** The operation contains an error. */
public static final String ERROR = "ERROR";

private OtelStatusCodeValues() {}
}

public static final class FaasTriggerValues {
/** A response to some data source operation such as a database or filesystem read/write. */
public static final String DATASOURCE = "datasource";
Expand Down Expand Up @@ -1425,5 +1525,13 @@ private MessageTypeValues() {}
*/
@Deprecated public static final AttributeKey<String> NET_HOST_IP = stringKey("net.host.ip");

/**
* The ordinal number of request re-sending attempt.
*
* @deprecated This item has been removed as of 1.15.0 of the semantic conventions. Use {@link
* SemanticAttributes#HTTP_RESEND_COUNT} instead.
*/
@Deprecated public static final AttributeKey<Long> HTTP_RETRY_COUNT = longKey("http.retry_count");

private SemanticAttributes() {}
}