diff --git a/.chloggen/661.yaml b/.chloggen/661.yaml new file mode 100644 index 0000000000..dde1142c34 --- /dev/null +++ b/.chloggen/661.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: messaging + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add messaging semantic conventions for settlement spans + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [621] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.chloggen/TEMPLATE.yaml b/.chloggen/TEMPLATE.yaml new file mode 100644 index 0000000000..b094f4d184 --- /dev/null +++ b/.chloggen/TEMPLATE.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.chloggen/config.yaml b/.chloggen/config.yaml new file mode 100644 index 0000000000..411f32d3a5 --- /dev/null +++ b/.chloggen/config.yaml @@ -0,0 +1,24 @@ +# The directory that stores individual changelog entries. +# Each entry is stored in a dedicated yaml file. +# - 'make chlog-new' will copy the 'template_yaml' to this directory as a new entry file. +# - 'make chlog-validate' will validate that all entry files are valid. +# - 'make chlog-update' will read and delete all entry files in this directory, and update 'changelog_md'. + +# Specify as relative path from root of repo. +# (Optional) Default: .chloggen +entries_dir: .chloggen + +# This file is used as the input for individual changelog entries. +# Specify as relative path from root of repo. +# (Optional) Default: .chloggen/TEMPLATE.yaml +template_yaml: .chloggen/TEMPLATE.yaml + +# The CHANGELOG file or files to which 'chloggen update' will write new entries +# (Optional) Default filename: CHANGELOG.md +change_logs: + user: CHANGELOG.md + +# The default change_log or change_logs to which an entry should be added. +# If 'change_logs' is specified in this file, and no value is specified for 'default_change_logs', +# then 'change_logs' MUST be specified in every entry file. +default_change_logs: [user] diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 40f8193207..0ea068d59c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,5 +9,6 @@ Note: if the PR is touching an area that is not listed in the [existing areas](h ## Merge requirement checklist * [ ] [CONTRIBUTING.md](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md) guidelines followed. -* [ ] [CHANGELOG.md](https://github.com/open-telemetry/semantic-conventions/blob/main/CHANGELOG.md) updated for non-trivial changes. +* [ ] Change log entry added, according to the guidelines in [When to add a changelog entry](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md#when-to-add-a-changelog-entry). + * If your PR does not need a change log, start the PR title with `[chore]` * [ ] [schema-next.yaml](https://github.com/open-telemetry/semantic-conventions/blob/main/schema-next.yaml) updated with changes to existing conventions. diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml new file mode 100644 index 0000000000..a5a390b69d --- /dev/null +++ b/.github/workflows/changelog.yml @@ -0,0 +1,88 @@ +# This action requires that any PR targeting the main branch should touch at +# least one CHANGELOG file. If a CHANGELOG entry is not required, add the "Skip +# Changelog" label to disable this action. + +name: 'Changelog' + +on: + pull_request: + types: [opened, ready_for_review, synchronize, reopened, labeled, unlabeled] + branches: + - main + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref }} + cancel-in-progress: true + +jobs: + changelog: + runs-on: ubuntu-latest + if: >- + ${{ + !contains(github.event.pull_request.labels.*.name, 'dependencies') && + !contains(github.event.pull_request.labels.*.name, 'Skip Changelog') && + !contains(github.event.pull_request.title, '[chore]') + }} + env: + PR_HEAD: ${{ github.event.pull_request.head.sha }} + steps: + - name: Checkout Repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup Go + uses: actions/setup-go@v4 + with: + go-version: ~1.21.6 + - name: Cache Go + id: go-cache + uses: actions/cache@v3 + with: + path: | + ~/go/bin + ~/go/pkg/mod + key: changelog-${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} + + - name: Ensure no changes to the CHANGELOG.md + run: | + if [[ $(git diff --name-only $(git merge-base origin/main $PR_HEAD) $PR_HEAD ./CHANGELOG*.md) ]] + then + echo "CHANGELOG.md should not be directly modified." + echo "Please add a .yaml file to the ./.chloggen/ directory." + echo "See CONTRIBUTING.md for more details." + echo "Alternately, add either \"[chore]\" to the title of the pull \ request or add the \"Skip Changelog\" label if this job should be skipped." + false + else + echo "CHANGELOG.md was not modified." + fi + + - name: Ensure ./.chloggen/*.yaml addition(s) + run: | + if [[ 1 -gt $(git diff --diff-filter=A --name-only $(git merge-base origin/main $PR_HEAD) $PR_HEAD ./.chloggen | grep -c \\.yaml) ]] + then + echo "No changelog entry was added to the ./.chloggen/ directory." + echo "Please add a .yaml file to the ./.chloggen/ directory." + echo "See CONTRIBUTING.md for more details." + echo "Alternately, add either \"[chore]\" to the title of the pull request or add the \"Skip Changelog\" label if this job should be skipped." + false + else + echo "A changelog entry was added to the ./.chloggen/ directory." + fi + + - name: Validate ./.chloggen/*.yaml changes + run: | + make chlog-validate \ + || { echo "New ./.chloggen/*.yaml file failed validation."; exit 1; } + + # In order to validate any links in the yaml file, render the config to markdown + - name: Render .chloggen changelog entries + run: make chlog-preview > changelog_preview.md + - name: Install markdown-link-check + run: npm install -g markdown-link-check + - name: Run markdown-link-check + run: | + markdown-link-check \ + --verbose \ + --config .markdown_link_check_config.json \ + changelog_preview.md \ + || { echo "Check that anchor links are lowercase"; exit 1; } diff --git a/.github/workflows/stale-pr.yml b/.github/workflows/stale-pr.yml new file mode 100644 index 0000000000..3b6ebf4168 --- /dev/null +++ b/.github/workflows/stale-pr.yml @@ -0,0 +1,18 @@ +name: "Close stale pull requests" +on: + schedule: + - cron: "12 3 * * *" # arbitrary time not to DDOS GitHub + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v9 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + stale-pr-message: 'This PR was marked stale due to lack of activity. It will be closed in 7 days.' + close-pr-message: 'Closed as inactive. Feel free to reopen if this PR is still being worked on.' + exempt-pr-labels: 'bug,work in progress,experts needed' + exempt-draft-pr: true + days-before-stale: 15 + days-before-close: 7 diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d0439c21a..c56d0a3dee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,11 @@ + + # Changelog -Please update changelog as part of any significant pull request. Place short -description of your change into "Unreleased" section. As part of release process -content of "Unreleased" section content will generate release notes for the -release. + ## Unreleased @@ -13,6 +15,8 @@ release. ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) - Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources ([#625](https://github.com/open-telemetry/semantic-conventions/pull/625)) +- Make `network.protocol.name` conditionally required for messaging + ([#644](https://github.com/open-telemetry/semantic-conventions/pull/644)) - BREAKING: Generate process metrics from YAML ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) - Rename `process.threads` to `process.thread.count` @@ -29,13 +33,21 @@ release. - `type` to `process.paging.fault_type` - BREAKING: Change type of `host.cpu.stepping` to string. ([#665](https://github.com/open-telemetry/semantic-conventions/pull/665)) +- Fix JVM buffer metric schema translations + ([#683](https://github.com/open-telemetry/semantic-conventions/pull/683)) ### Features - Add `azure_container_apps` to `cloud.platform` semantic conventions ([#615](https://github.com/open-telemetry/semantic-conventions/pull/615)) +- Add `user_agent.name` and `user_agent.version` attributes + ([#452](https://github.com/open-telemetry/semantic-conventions/pull/452/)) - Add an example for gcp_pubsub asynchronous batch publish - ([#545](https://github.com/open-telemetry/semantic-conventions/pull/545)). + ([#545](https://github.com/open-telemetry/semantic-conventions/pull/545)) +- Add `aws.ecs.task.id` attribute, corrected description for `aws.ecs.task.arn`. + ([#597](https://github.com/open-telemetry/semantic-conventions/pull/597)) +- Add Azure Service Bus and Event Hubs messaging attributes + ([#572](https://github.com/open-telemetry/semantic-conventions/pull/572)) ### Fixes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0bfa90bc98..0639de51d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,38 @@ Before you start - see OpenTelemetry general [contributing](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) requirements and recommendations. +
+Table of Contents + + + +- [Sign the CLA](#sign-the-cla) +- [How to Contribute](#how-to-contribute) + * [Prerequisites](#prerequisites) + * [1. Modify the YAML model](#1-modify-the-yaml-model) + + [Schema files](#schema-files) + * [2. Update the markdown files](#2-update-the-markdown-files) + + [Hugo frontmatter](#hugo-frontmatter) + * [3. Verify the changes before committing](#3-verify-the-changes-before-committing) + * [4. Changelog](#4-changelog) + + [When to add a Changelog Entry](#when-to-add-a-changelog-entry) + - [Examples](#examples) + + [Adding a Changelog Entry](#adding-a-changelog-entry) + * [5. Getting your PR merged](#5-getting-your-pr-merged) +- [Automation](#automation) + * [Consistency Checks](#consistency-checks) + * [Auto formatting](#auto-formatting) + * [Markdown style](#markdown-style) + * [Misspell check](#misspell-check) + * [Markdown link check](#markdown-link-check) +- [Updating the referenced specification version](#updating-the-referenced-specification-version) +- [Making a Release](#making-a-release) +- [Merging existing ECS conventions](#merging-existing-ecs-conventions) + + + +
+ ## Sign the CLA Before you can contribute, you will need to sign the [Contributor License @@ -18,31 +50,70 @@ key, but non-obvious, aspects: - All attributes, metrics, etc. are formally defined in YAML files under the `model/` directory. -- All descriptions, normative language are defined in the `docs/` - directory. - - We provide tooling to generate Markdown documentation from the formal - YAML definitons. See [Yaml to Markdown](#yaml-to-markdown). - - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/). - You will see ` ``` -When creating new pages, you should provide the `linkTitle` attribute. This is used -to generate the navigation bar on the website, and will be listed relative to the -"parent" document. +When creating new markdown files, you should provide the `linkTitle` attribute. +This is used to generate the navigation bar on the website, +and will be listed relative to the "parent" document. -## Automation +### 3. Verify the changes before committing -Semantic Conventions provides a set of automated tools for general development. +Before sending a PR with your changes, make sure to run the automated checks: -### Consistency Checks +```bash +make check +``` -The Specification has a number of tools it uses to check things like style, -spelling and link validity. Before using the tools: +Alternatively, you can run each check individually. +Refer to the [Automation](#automation) section for more details. -- Install the latest LTS release of **[Node](https://nodejs.org/)**. - For example, using **[nvm][]** under Linux run: +### 4. Changelog - ```bash - nvm install --lts - ``` +#### When to add a Changelog Entry -- Install tooling packages: +Pull requests that contain user-facing changes will require a changelog entry. +Keep in mind the following types of users (not limited to): - ```bash - npm install - ``` +1. Those who are consuming the data following these conventions (e.g., in alerts, dashboards, queries) +2. Those who are using the conventions in instrumentations (e.g., library authors) +3. Those who are using the conventions to derive heuristics, predictions and automatic analyses (e.g., observability products/back-ends) + +If a changelog entry is not required (e.g. editorial or trivial changes), +a maintainer or approver will add the `Skip Changelog` label to the pull request. + +##### Examples + +Changelog entry required: + +- Any modification to existing conventions with change in functionality/behavior +- New semantic conventions +- Changes on definitions, normative language (in `/docs`) + +No changelog entry: + +- Typical documentation/editorial updates (e.g. grammar fixes, restructuring) +- Changes in internal tooling (e.g. make file, GH actions, etc) +- Refactorings with no meaningful change in functionality +- Chores, such as enabling linters, updating dependencies + +#### Adding a Changelog Entry + +The [CHANGELOG.md](./CHANGELOG.md) files in this repo is autogenerated +from `.yaml` files in the [/.chloggen](/.chloggen) directory. + +Your pull request should add a new `.yaml` file to this directory. +The name of your file can be arbitrary but must be unique since the last release. + +During the release process, all `./.chloggen/*.yaml` files are transcribed into +`CHANGELOG.md` and then deleted. + +1. Create an entry file using `make chlog-new`. The command generates a new file, + with its name based on the current branch (e.g. `./.chloggen/my-feature-xyz.yaml`) +2. Fill in all the fields in the generated file +3. The value for the `component` field MUST match a filename (without type) in the + [registry](https://github.com/open-telemetry/semantic-conventions/tree/main/model/registry) + (e.g. `browser`, `http`) +4. Run `make chlog-validate` to ensure the new file is valid +5. Commit and push the file + +Alternately, copy `./.chloggen/TEMPLATE.yaml`, or just create your file from scratch. + +### 5. Getting your PR merged + +A PR (pull request) is considered to be **ready to merge** when: + +- It has received at least two approvals from the [code + owners](./.github/CODEOWNERS) (if approvals are from only one company, they + won't count) +- There is no `request changes` from the [code owners](./.github/CODEOWNERS) +- There is no open discussions +- It has been at least two working days since the last modification (except for + the trivial updates, such like typo, cosmetic, rebase, etc.). This gives + people reasonable time to review +- Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to + wait for two days + +Any [maintainer](./README.md#contributing) can merge the PR once it is **ready +to merge**. + +## Automation + +Semantic Conventions provides a set of automated tools for general development. + +### Consistency Checks + +The Specification has a number of tools it uses to check things like style, +spelling and link validity. You can perform all checks locally using this command: @@ -83,23 +221,18 @@ You can perform all checks locally using this command: make check ``` -Note: This can take a long time as it checks all links. You should use this -prior to submitting a PR to ensure validity. However, you can run individual -checks directly. +> Note: `make check` can take a long time as it checks all links. +> You should use this prior to submitting a PR to ensure validity. +> However, you can run individual checks directly. -See: +For more information on each check, see: -- [MarkdownStyle](#markdown-style) -- [Misspell Check](#misspell-check) -- Markdown link checking (docs TODO) +- [Markdown style](#markdown-style) +- [Misspell check](#misspell-check) +- [Markdown link check](#markdown-link-check) - Prettier formatting -### YAML to Markdown - -Semantic conventions are declared in YAML files and markdown tables are -generated from these files. Read about semantic convention updates [here](./model/README.md). - -### Autoformatting +### Auto formatting Semantic conventions have some autogenerated components and additionally can do automatic style/spell correction. You can run all of this via: @@ -113,7 +246,7 @@ You can also run these fixes individually. See: - [Misspell Correction](#misspell-check) -- Table Generation (docs TODO) +- [Update the markdown files](#2-update-the-markdown-files) ### Markdown style @@ -159,22 +292,13 @@ To quickly fix typos, use make misspell-correction ``` -### How to get your PR merged +### Markdown link check -A PR (pull request) is considered to be **ready to merge** when: +To check the validity of links in all markdown files, run the following command: -- It has received at least two approvals from the [code - owners](./.github/CODEOWNERS) (if approvals are from only one company, they - won't count). -- There is no `request changes` from the [code owners](./.github/CODEOWNERS). -- It has been at least two working days since the last modification (except for - the trivial updates, such like typo, cosmetic, rebase, etc.). This gives - people reasonable time to review. -- Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to - wait for two days. - -Any [maintainer](./README.md#contributing) can merge the PR once it is **ready -to merge**. +```bash +make markdown-link-check +``` ## Updating the referenced specification version @@ -194,8 +318,10 @@ to merge**. - Ensure the `next` version is appropriately configured as the `{version}`. - Copy `schema-next.yaml` to `schemas/{version}`. - Add `next` as a version in `schema-next.yaml` version. - - Update `CHANGELOG.md` for the latest version. - - Add `## v{version} ({date})` under `## Unreleased` + - Run `make chlog-update VERSION=v{version}` + - `make chlog-update` will clean up all the current `.yaml` files inside the + `.chloggen` folder automatically + - Double check that `CONTRIBUTING.md` is updated with the proper `v{version}` - Send staging tag as PR for review. - Create a tag `v{version}` on the merged PR and push remote. diff --git a/Makefile b/Makefile index acbb7f7de7..b0a1e81e95 100644 --- a/Makefile +++ b/Makefile @@ -3,9 +3,14 @@ ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -p PWD := $(shell pwd) TOOLS_DIR := ./internal/tools + MISSPELL_BINARY=bin/misspell MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) +CHLOGGEN_BINARY=bin/chloggen +CHLOGGEN = $(TOOLS_DIR)/$(CHLOGGEN_BINARY) +CHLOGGEN_CONFIG := .chloggen/config.yaml + # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.23.0 @@ -124,3 +129,23 @@ fix: table-generation misspell-correction fix-format install-tools: $(MISSPELL) npm install @echo "All tools installed" + +$(CHLOGGEN): + cd $(TOOLS_DIR) && go build -o $(CHLOGGEN_BINARY) go.opentelemetry.io/build-tools/chloggen + +FILENAME?=$(shell git branch --show-current) +.PHONY: chlog-new +chlog-new: $(CHLOGGEN) + $(CHLOGGEN) new --config $(CHLOGGEN_CONFIG) --filename $(FILENAME) + +.PHONY: chlog-validate +chlog-validate: $(CHLOGGEN) + $(CHLOGGEN) validate --config $(CHLOGGEN_CONFIG) + +.PHONY: chlog-preview +chlog-preview: $(CHLOGGEN) + $(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --dry + +.PHONY: chlog-update +chlog-update: $(CHLOGGEN) + $(CHLOGGEN) update --config $(CHLOGGEN_CONFIG) --version $(VERSION) diff --git a/docs/README.md b/docs/README.md index 498f5e739c..e15b61dfaa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,10 +5,10 @@ cascade: body_class: otel-docs-spec github_repo: &repo https://github.com/open-telemetry/semantic-conventions github_subdir: docs - path_base_for_github_subdir: content/en/docs/specs/semconv/ + path_base_for_github_subdir: tmp/semconv/docs/ github_project_repo: *repo path_base_for_github_subdir: - from: content/en/docs/specs/semconv/_index.md + from: tmp/semconv/docs/_index.md to: README.md ---> diff --git a/docs/attributes-registry/host.md b/docs/attributes-registry/host.md index 950ebfcbef..a8c1de6e3f 100644 --- a/docs/attributes-registry/host.md +++ b/docs/attributes-registry/host.md @@ -1,5 +1,6 @@ + # Host ## Host Attributes diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index c874710646..2ec5ad6c2d 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -10,6 +10,8 @@ - [Kafka Attributes](#kafka-attributes) - [RabbitMQ Attributes](#rabbitmq-attributes) - [RocketMQ Attributes](#rocketmq-attributes) +- [Azure Event Hubs Attributes](#azure-event-hubs-attributes) +- [Azure Service Bus Attributes](#azure-service-bus-attributes) @@ -66,9 +68,9 @@ size should be used. |---|---| | `activemq` | Apache ActiveMQ | | `aws_sqs` | Amazon Simple Queue Service (SQS) | -| `azure_eventgrid` | Azure Event Grid | -| `azure_eventhubs` | Azure Event Hubs | -| `azure_servicebus` | Azure Service Bus | +| `eventgrid` | Azure Event Grid | +| `eventhubs` | Azure Event Hubs | +| `servicebus` | Azure Service Bus | | `gcp_pubsub` | Google Cloud Pub/Sub | | `jms` | Java Message Service | | `kafka` | Apache Kafka | @@ -137,3 +139,23 @@ size should be used. | `delay` | Delay message | | `transaction` | Transaction message | + +## Azure Event Hubs Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.eventhubs.consumer.group` | string | The name of the consumer group the event consumer is associated with. | `indexer` | +| `messaging.eventhubs.destination.partition.id` | string | The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. | `1` | +| `messaging.eventhubs.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | + + +## Azure Service Bus Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.servicebus.destination.subscription_name` | string | The name of the subscription in the topic messages are received from. | `mySubscription` | +| `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` | +| `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | + diff --git a/docs/attributes-registry/os.md b/docs/attributes-registry/os.md index a813298f98..1a9df99771 100644 --- a/docs/attributes-registry/os.md +++ b/docs/attributes-registry/os.md @@ -1,6 +1,7 @@ + # OS ## Operating System Attributes diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md index 5b1aa7c0d8..c7a22357b7 100644 --- a/docs/attributes-registry/url.md +++ b/docs/attributes-registry/url.md @@ -1,6 +1,7 @@ + # URL ## URL Attributes diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 589f722f87..f75c5d22ce 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -8,5 +8,11 @@ | Attribute | Type | Description | Examples | |---|---|---|---| +| `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name [1] | `Safari` | | `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | +| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2` | + +**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string + +**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string diff --git a/docs/cloud-providers/README.md b/docs/cloud-providers/README.md index 4b213871fe..8e88f408fc 100644 --- a/docs/cloud-providers/README.md +++ b/docs/cloud-providers/README.md @@ -1,7 +1,7 @@ diff --git a/docs/cloudevents/README.md b/docs/cloudevents/README.md index b5c2c20ad7..beb6527e62 100644 --- a/docs/cloudevents/README.md +++ b/docs/cloudevents/README.md @@ -1,7 +1,7 @@ diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 4064262d1d..1236b745ad 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -40,7 +40,7 @@ document. A CloudEvent can be sent directly from producer to consumer. For such a scenario, the traditional parent-child trace model works well. However, CloudEvents are also used in distributed systems where an event -can go through many [hops]() +can go through many [hops](https://en.wikipedia.org/wiki/Hop_%28networking%29) until it reaches a consumer. In this scenario, the traditional parent-child trace model is not sufficient to produce a meaningful trace. diff --git a/docs/database/README.md b/docs/database/README.md index 50d42dd7cb..8ef9dd98c9 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -1,7 +1,7 @@ diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 763e7a1b12..239be3960b 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -6,7 +6,7 @@ linkTitle: MSSQL **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for the [Microsoft SQL Server](https://www.microsoft.com/sql-server) extend and override the [Database Semantic Conventions](database-spans.md) +The Semantic Conventions for the *Microsoft SQL Server* extend and override the [Database Semantic Conventions](database-spans.md) that describe common database operations attributes in addition to the Semantic Conventions described on this page. diff --git a/docs/dotnet/README.md b/docs/dotnet/README.md index 1bc9673359..a8b5f7bbd2 100644 --- a/docs/dotnet/README.md +++ b/docs/dotnet/README.md @@ -1,7 +1,7 @@ diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index 4e074df495..4632585126 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -1,7 +1,7 @@ diff --git a/docs/faas/README.md b/docs/faas/README.md index bdf3b05222..19ab9d3131 100644 --- a/docs/faas/README.md +++ b/docs/faas/README.md @@ -1,7 +1,7 @@ diff --git a/docs/feature-flags/README.md b/docs/feature-flags/README.md index 1eb70a28e3..a55b42b7d9 100644 --- a/docs/feature-flags/README.md +++ b/docs/feature-flags/README.md @@ -1,7 +1,7 @@ diff --git a/docs/general/README.md b/docs/general/README.md index ec1e248fda..a4bff5597e 100644 --- a/docs/general/README.md +++ b/docs/general/README.md @@ -1,7 +1,7 @@ diff --git a/docs/http/README.md b/docs/http/README.md index c4ae8a10d2..4bd1e41f73 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -1,7 +1,7 @@ diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 1193cf2cb0..9ed7173c1b 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -277,7 +277,7 @@ Retries and redirects cause more than one physical HTTP request to be sent. A request is resent when an HTTP client library sends more than one HTTP request to satisfy the same API call. This may happen due to following redirects, authorization challenges, 503 Server Unavailable, network issues, or any other. -Each time an HTTP request is resent, the `http.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. +Each time an HTTP request is resent, the `http.request.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. See the examples for more details about: @@ -433,11 +433,11 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET / - 500 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET / - 500 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | | | --- server (SERVER, trace=t1, span=s5) | - -- GET / - 200 (CLIENT, trace=t1, span=s6, http.resend_count=2) + -- GET / - 200 (CLIENT, trace=t1, span=s6, http.request.resend_count=2) | --- server (SERVER, trace=t1, span=s7) ``` @@ -449,11 +449,11 @@ GET / - 500 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET / - 500 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET / - 500 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) -GET / - 200 (CLIENT, trace=t3, span=s1, http.resend_count=2) +GET / - 200 (CLIENT, trace=t3, span=s1, http.request.resend_count=2) | --- server (SERVER, trace=t3, span=s1) ``` @@ -469,7 +469,7 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | --- server (SERVER, trace=t1, span=s5) ``` @@ -481,7 +481,7 @@ GET /hello - 401 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET /hello - 200 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) ``` @@ -497,7 +497,7 @@ request (SERVER, trace=t1, span=s1) | | | --- server (SERVER, trace=t1, span=s3) | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) + -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.request.resend_count=1) | --- server (SERVER, trace=t1, span=s5) ``` @@ -509,7 +509,7 @@ GET / - 302 (CLIENT, trace=t1, span=s1) | --- server (SERVER, trace=t1, span=s2) -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) +GET /hello - 200 (CLIENT, trace=t2, span=s1, http.request.resend_count=1) | --- server (SERVER, trace=t2, span=s2) ``` diff --git a/docs/messaging/README.md b/docs/messaging/README.md index 5308786270..2ba98b5977 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -1,7 +1,7 @@ diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md new file mode 100644 index 0000000000..35e17ec2c3 --- /dev/null +++ b/docs/messaging/azure-messaging.md @@ -0,0 +1,43 @@ + + +# Semantic Conventions for Azure Messaging systems + +**Status**: [Experimental][DocumentStatus] + +The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview) and [Azure Event Hubs](https://learn.microsoft.com/azure/event-hubs/event-hubs-about) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. + +## Azure Service Bus + +`messaging.system` MUST be set to `"servicebus"`. + +### Span attributes + +The following additional attributes are defined: + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`messaging.servicebus.destination.subscription_name`](../attributes-registry/messaging.md) | string | The name of the subscription in the topic messages are received from. | `mySubscription` | Conditionally Required: If messages are received from the subscription. | +| [`messaging.servicebus.message.delivery_count`](../attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | Conditionally Required: [1] | +| [`messaging.servicebus.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended | + +**[1]:** If delivery count is available and is bigger than 0. + + +## Azure Event Hubs + +`messaging.system` MUST be set to `"eventhubs"`. + +### Span attributes + +The following additional attributes are defined: + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`messaging.eventhubs.consumer.group`](../attributes-registry/messaging.md) | string | The name of the consumer group the event consumer is associated with. | `indexer` | Conditionally Required: If not default ("$Default"). | +| [`messaging.eventhubs.destination.partition.id`](../attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. | `1` | Conditionally Required: If available. | +| [`messaging.eventhubs.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index b2f7046bdd..dc9d1ef9b0 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -29,10 +29,10 @@ All messaging metrics share the same set of attributes: | [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] | | [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. | | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | -| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `3.1.1` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Conditionally Required: [7] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [8] | `3.1.1` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | Recommended | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -61,11 +61,13 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[6]:** The value SHOULD be normalized to lowercase. -**[7]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[7]:** Only for messaging systems and frameworks that support more than one protocol. -**[8]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[8]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[10]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -79,9 +81,9 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi |---|---| | `activemq` | Apache ActiveMQ | | `aws_sqs` | Amazon Simple Queue Service (SQS) | -| `azure_eventgrid` | Azure Event Grid | -| `azure_eventhubs` | Azure Event Hubs | -| `azure_servicebus` | Azure Service Bus | +| `eventgrid` | Azure Event Grid | +| `eventhubs` | Azure Event Hubs | +| `servicebus` | Azure Service Bus | | `gcp_pubsub` | Google Cloud Pub/Sub | | `jms` | Java Message Service | | `kafka` | Apache Kafka | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index b80eec3a84..33e7d9ba29 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -184,18 +184,19 @@ If the destination name is dynamic, such as a [conversation ID](#conversations) In these cases, an artificial destination name that best expresses the destination, or a generic, static fallback like `"(anonymous)"` for [anonymous destinations](#temporary-and-anonymous-destinations) SHOULD be used instead. The values allowed for `` are defined in the section [Operation names](#operation-names) below. -If the format above is used, the operation name MUST match the `messaging.operation` attribute defined for message consumer spans below. Examples: * `shop.orders publish` * `shop.orders receive` -* `shop.orders process` +* `shop.orders settle` * `print_jobs publish` -* `topic with spaces process` -* `AuthenticationRequest-Conversations process` +* `topic with spaces deliver` +* `AuthenticationRequest-Conversations settle` * `(anonymous) publish` (`(anonymous)` being a stable identifier for an unnamed destination) +Messaging system specific adaptions to span naming MUST be documented in [semantic conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies). + ### Operation names The following operations related to messages are defined for these semantic conventions: @@ -206,6 +207,7 @@ The following operations related to messages are defined for these semantic conv | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | | `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. | +| `settle` | One or more messages are settled. | ### Span kind @@ -269,6 +271,12 @@ batch of messages, or for no message at all (if it is signalled that no messages were received). For each message it accounts for, the "Deliver" or "Receive" span SHOULD link to the message's creation context. +"Settle" spans SHOULD be created for every manually or automatically triggered +settlement operation. A single "Settle" span can account for a single message +or for multiple messages (in case messages are passed for settling as batches). +For each message it accounts for, the "Settle" span MAY link to the creation +context of the message. + ## Messaging attributes Messaging attributes are organized into the following namespaces: @@ -302,12 +310,12 @@ as described in [Attributes specific to certain messaging systems](#attributes-s | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [15] | `3.1.1` | Recommended | -| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [16] | `tcp`; `udp` | Recommended | -| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [17] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | -| [`server.port`](../attributes-registry/server.md) | int | Server port number. [19] | `80`; `8080`; `443` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Conditionally Required: [15] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [16] | `3.1.1` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [18] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [19] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [20] | `80`; `8080`; `443` | Recommended | **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -354,19 +362,21 @@ size should be used. **[14]:** The value SHOULD be normalized to lowercase. -**[15]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[15]:** Only for messaging systems and frameworks that support more than one protocol. -**[16]:** The value SHOULD be normalized to lowercase. +**[16]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[17]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[17]:** The value SHOULD be normalized to lowercase. +**[18]:** The value SHOULD be normalized to lowercase. -**[18]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[19]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[19]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[20]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -389,9 +399,9 @@ different processes could be listening on TCP port 12345 and UDP port 12345. |---|---| | `activemq` | Apache ActiveMQ | | `aws_sqs` | Amazon Simple Queue Service (SQS) | -| `azure_eventgrid` | Azure Event Grid | -| `azure_eventhubs` | Azure Event Hubs | -| `azure_servicebus` | Azure Service Bus | +| `eventgrid` | Azure Event Grid | +| `eventhubs` | Azure Event Hubs | +| `servicebus` | Azure Service Bus | | `gcp_pubsub` | Google Cloud Pub/Sub | | `jms` | Java Message Service | | `kafka` | Apache Kafka | diff --git a/docs/mobile/README.md b/docs/mobile/README.md index bcf994e485..cc6ffb6285 100644 --- a/docs/mobile/README.md +++ b/docs/mobile/README.md @@ -1,7 +1,7 @@ diff --git a/docs/object-stores/README.md b/docs/object-stores/README.md index da6a0d8612..67637442ee 100644 --- a/docs/object-stores/README.md +++ b/docs/object-stores/README.md @@ -1,7 +1,7 @@ diff --git a/docs/resource/README.md b/docs/resource/README.md index a77cbd2f69..c67b8f3517 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -1,7 +1,7 @@ @@ -20,7 +20,7 @@ This document defines standard attributes for resources. These attributes are ty - [Document Conventions](#document-conventions) - [Attributes with Special Handling](#attributes-with-special-handling) * [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) -- [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) + * [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) - [Service (Experimental)](#service-experimental) - [Telemetry SDK](#telemetry-sdk) @@ -63,7 +63,7 @@ as specified in [OpenTelemetry Environment Variable Specification](https://githu - [`service.name`](#service) -## Semantic Attributes with SDK-provided Default Value +### Semantic Attributes with SDK-provided Default Value These are the attributes which MUST be provided by the SDK as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/resource/sdk.md#sdk-provided-resource-attributes): diff --git a/docs/resource/cloud-provider/README.md b/docs/resource/cloud-provider/README.md index 9d4757a6c0..1be2cbd21c 100644 --- a/docs/resource/cloud-provider/README.md +++ b/docs/resource/cloud-provider/README.md @@ -1,7 +1,7 @@ diff --git a/docs/resource/cloud-provider/aws/README.md b/docs/resource/cloud-provider/aws/README.md index 2ac32239e5..1409a89b5f 100644 --- a/docs/resource/cloud-provider/aws/README.md +++ b/docs/resource/cloud-provider/aws/README.md @@ -1,7 +1,7 @@ diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index 362b66dde9..2edafe56b9 100644 --- a/docs/resource/cloud-provider/aws/ecs.md +++ b/docs/resource/cloud-provider/aws/ecs.md @@ -12,9 +12,10 @@ | `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | | `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended | | `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | Recommended | -| `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | Recommended | -| `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | Recommended | -| `aws.ecs.task.revision` | string | The revision for this task definition. | `8`; `26` | Recommended | +| `aws.ecs.task.arn` | string | The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b`; `arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | Recommended | +| `aws.ecs.task.family` | string | The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. | `opentelemetry-family` | Recommended | +| `aws.ecs.task.id` | string | The ID of a running ECS task. The ID MUST be extracted from `task.arn`. | `10838bed-421f-43ef-870a-f43feacbbb5b`; `23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | Conditionally Required: If and only if `task.arn` is populated. | +| `aws.ecs.task.revision` | string | The revision for the task definition used to create the ECS task. | `8`; `26` | Recommended | `aws.ecs.launchtype` MUST be one of the following: diff --git a/docs/resource/cloud-provider/gcp/README.md b/docs/resource/cloud-provider/gcp/README.md index 1e975ff9db..6b115235ea 100644 --- a/docs/resource/cloud-provider/gcp/README.md +++ b/docs/resource/cloud-provider/gcp/README.md @@ -1,7 +1,7 @@ diff --git a/docs/rpc/README.md b/docs/rpc/README.md index c7810685b4..353f6bce85 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -1,7 +1,7 @@ diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 7c913815e2..780c15afd3 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -188,6 +188,8 @@ of `[ 0.01, 0.1, 1, 10 ]`. ## JVM Threads +**Status**: [Stable][DocumentStatus] + **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.thread.*` ### Metric: `jvm.thread.count` @@ -228,6 +230,8 @@ Note that this is the number of platform threads (as opposed to virtual threads) ## JVM Classes +**Status**: [Stable][DocumentStatus] + **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.class.*` ### Metric: `jvm.class.loaded` diff --git a/docs/system/README.md b/docs/system/README.md index a05a0bf9e8..a3422a342f 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -1,7 +1,7 @@ diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index 09ba773b65..a5c9f8ac01 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -309,7 +309,7 @@ Additional **Recommended** attributes: | | | | | | `hw.type` (**Required**) | `physical_disk` | | `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (**Required**) | `remaining` | | `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | | -| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. | +| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. | | `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` | | | | | | | `hw.type` (**Required**) | `physical_disk` | diff --git a/docs/url/README.md b/docs/url/README.md index 6c863191ae..61c2398793 100644 --- a/docs/url/README.md +++ b/docs/url/README.md @@ -1,7 +1,7 @@ diff --git a/internal/tools/go.mod b/internal/tools/go.mod index aeac23a1d3..d0b9f54cf0 100644 --- a/internal/tools/go.mod +++ b/internal/tools/go.mod @@ -2,4 +2,7 @@ module github.com/open-telemetry/opentelemetry-specification/internal/tools go 1.12 -require github.com/client9/misspell v0.3.4 +require ( + github.com/client9/misspell v0.3.4 + go.opentelemetry.io/build-tools/chloggen v0.12.0 +) diff --git a/internal/tools/go.sum b/internal/tools/go.sum index ee5948021f..67e22ae48f 100644 --- a/internal/tools/go.sum +++ b/internal/tools/go.sum @@ -1,2 +1,29 @@ github.com/client9/misspell v0.3.4 h1:ta993UF76GwbvJcIo3Y68y/M3WxlpEHPWIGDkJYwzJI= github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= +github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.7.0 h1:hyqWnYt1ZQShIddO5kBpj3vu05/++x6tJ6dg8EC572I= +github.com/spf13/cobra v1.7.0/go.mod h1:uLxZILRyS/50WlhOIKD7W6V5bgeIt+4sICxh6uRMrb0= +github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= +github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw= +github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo= +github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= +github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= +github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= +go.opentelemetry.io/build-tools/chloggen v0.12.0 h1:BFj/1bNIGxOs1GykGjhV4gycz1nqVWI/xVDUaVfNibw= +go.opentelemetry.io/build-tools/chloggen v0.12.0/go.mod h1:zuYbAo3TkrHo3C7lCrM5dHWSS50BDr0UfRYtyBFv2dQ= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/internal/tools/tools.go b/internal/tools/tools.go index bfa021b18f..2a785effdd 100644 --- a/internal/tools/tools.go +++ b/internal/tools/tools.go @@ -13,6 +13,7 @@ // limitations under the License. // +//go:build tools // +build tools package tools @@ -24,4 +25,5 @@ package tools import ( _ "github.com/client9/misspell/cmd/misspell" + _ "go.opentelemetry.io/build-tools/chloggen" ) diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml index 07ef5f4a78..92bddd7924 100644 --- a/model/messaging-common.yaml +++ b/model/messaging-common.yaml @@ -18,6 +18,8 @@ groups: - ref: server.port - ref: network.protocol.name examples: ['amqp', 'mqtt'] + requirement_level: + conditionally_required: Only for messaging systems and frameworks that support more than one protocol. tag: connection-level - ref: network.protocol.version tag: connection-level diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 6f638976a3..868df05065 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -248,14 +248,14 @@ groups: - id: aws_sqs value: 'aws_sqs' brief: 'Amazon Simple Queue Service (SQS)' - - id: azure_eventgrid - value: 'azure_eventgrid' + - id: eventgrid + value: 'eventgrid' brief: 'Azure Event Grid' - - id: azure_eventhubs - value: 'azure_eventhubs' + - id: eventhubs + value: 'eventhubs' brief: 'Azure Event Hubs' - - id: azure_servicebus - value: 'azure_servicebus' + - id: servicebus + value: 'servicebus' brief: 'Azure Service Bus' - id: gcp_pubsub value: 'gcp_pubsub' @@ -273,3 +273,39 @@ groups: value: 'rocketmq' brief: 'Apache RocketMQ' tag: messaging-generic + - id: servicebus.message.delivery_count + type: int + brief: > + Number of deliveries that have been attempted for this message. + examples: 2 + tag: tech-specific-servicebus + - id: servicebus.message.enqueued_time + type: int + brief: > + The UTC epoch seconds at which the message has been accepted and stored in the entity. + examples: 1701393730 + tag: tech-specific-servicebus + - id: servicebus.destination.subscription_name + type: string + brief: > + The name of the subscription in the topic messages are received from. + examples: "mySubscription" + tag: tech-specific-servicebus + - id: eventhubs.message.enqueued_time + type: int + brief: > + The UTC epoch seconds at which the message has been accepted and stored in the entity. + examples: 1701393730 + tag: tech-specific-eventhubs + - id: eventhubs.destination.partition.id + type: string + brief: > + The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. + examples: '1' + tag: tech-specific-eventhubs + - id: eventhubs.consumer.group + type: string + brief: > + The name of the consumer group the event consumer is associated with. + examples: 'indexer' + tag: tech-specific-eventhubs diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 0fbc5c9f2a..29e00ff6bc 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -11,3 +11,17 @@ groups: Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. examples: ['CERN-LineMode/2.15 libwww/2.17b3', 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] + - id: name + type: string + brief: > + Name of the user-agent extracted from original. Usually refers to the browser's name + examples: ['Safari'] + note: > + [Example](https://www.whatsmyua.info) of extracting browser's name from original string + - id: version + type: string + brief: > + Version of the user-agent extracted from original. Usually refers to the browser's version + examples: ['14.1.2'] + note: > + [Example](https://www.whatsmyua.info) of extracting browser's version from original string diff --git a/model/resource/cloud_provider/aws/ecs.yaml b/model/resource/cloud_provider/aws/ecs.yaml index 2c6b8c9ba5..a40f950c18 100644 --- a/model/resource/cloud_provider/aws/ecs.yaml +++ b/model/resource/cloud_provider/aws/ecs.yaml @@ -28,15 +28,25 @@ groups: - id: task.arn type: string brief: > - The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). - examples: ['arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b'] + The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). + examples: [ + 'arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b', + 'arn:aws:ecs:us-west-1:123456789123:task/my-cluster/task-id/23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' + ] - id: task.family type: string brief: > - The task definition family this task definition is a member of. + The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. examples: ['opentelemetry-family'] + - id: task.id + type: string + brief: > + The ID of a running ECS task. The ID MUST be extracted from `task.arn`. + requirement_level: + conditionally_required: If and only if `task.arn` is populated. + examples: [ '10838bed-421f-43ef-870a-f43feacbbb5b', '23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' ] - id: task.revision type: string brief: > - The revision for this task definition. + The revision for the task definition used to create the ECS task. examples: ["8", "26"] diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 011ad09570..cc980de321 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -164,3 +164,29 @@ groups: tag: tech-specific-gcp-pubsub requirement_level: conditionally_required: If the message type has an ordering key set. + - id: messaging.servicebus + type: attribute_group + extends: messaging + brief: > + Attributes for Azure Service Bus + attributes: + - ref: messaging.servicebus.message.delivery_count + requirement_level: + conditionally_required: If delivery count is available and is bigger than 0. + - ref: messaging.servicebus.message.enqueued_time + - ref: messaging.servicebus.destination.subscription_name + requirement_level: + conditionally_required: If messages are received from the subscription. + - id: messaging.eventhubs + type: attribute_group + extends: messaging + brief: > + Attributes for Azure Event Hubs + attributes: + - ref: messaging.eventhubs.message.enqueued_time + - ref: messaging.eventhubs.destination.partition.id + requirement_level: + conditionally_required: If available. + - ref: messaging.eventhubs.consumer.group + requirement_level: + conditionally_required: If not default ("$Default"). diff --git a/schema-next.yaml b/schema-next.yaml index 23ebad9a35..441f34e983 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -140,8 +140,8 @@ versions: attribute_map: pool: jvm.buffer.pool.name apply_to_metrics: - - jvm.buffer.usage - - jvm.buffer.limit + - jvm.buffer.memory.usage + - jvm.buffer.memory.limit - jvm.buffer.count # https://github.com/open-telemetry/semantic-conventions/pull/89 - rename_attributes: