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.

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

Add pull request checks back for links/markdown. #5

Merged
merged 8 commits into from
May 11, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions .github/workflows/checks.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
name: Checks

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
markdownlint:
runs-on: ubuntu-latest
steps:
- name: check out code
uses: actions/checkout@v2

- name: install dependencies
run: npm install

- name: run markdownlint
run: make markdownlint

yamllint:
runs-on: ubuntu-latest
steps:
- name: check out code
uses: actions/checkout@v2

- uses: actions/setup-python@v2

- name: install yamllint
run: make install-yamllint

- name: run yamllint
run: yamllint . -f github

markdown-link-check:
runs-on: ubuntu-latest
steps:
- name: check out code
uses: actions/checkout@v2

- name: install dependencies
run: npm install

- name: run markdown-link-check
run: make markdown-link-check

markdown-toc-check:
runs-on: ubuntu-latest
steps:
- name: check out code
uses: actions/checkout@v2

- name: install dependencies
run: npm install

- name: run markdown-toc
run: make markdown-toc

- name: validate markdown-toc
run: git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1)

misspell:
runs-on: ubuntu-latest
steps:
- name: check out code
uses: actions/checkout@v2

- name: run misspell
run: make misspell

docfx:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-dotnet@v1
with:
dotnet-version: 6.0.x

- name: install docfx
run: dotnet tool update -g docfx --version "3.0.0-*" --add-source https://docfx.pkgs.visualstudio.com/docfx/_packaging/docs-public-packages/nuget/v3/index.json

- name: run docfx
run: docfx build --dry-run

semantic-conventions:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: verify semantic convention tables
run: make table-check

schemas-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: verify schemas
run: make schema-check
2 changes: 0 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,5 +114,3 @@ To quickly fix typos, use
```bash
make misspell-correction
```


1 change: 0 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ The documentation currently resides in the previous folders, e.g.
- [Metrics](specification/metrics/semantic_conventions/README.md)
- [Logs](specification/logs/semantic_conventions/README.md)


## TODOs

- [ ] Set up github actions
Expand Down
6 changes: 3 additions & 3 deletions semantic_conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ i.e.:
## Writing semantic conventions

Semantic conventions for the spec MUST adhere to the
[attribute naming](../specification/common/attribute-naming.md),
[attribute requirement level](../specification/common/attribute-requirement-level.md),
and [metric requirement level](../specification/metrics/metric-requirement-level.md) conventions.
[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-naming.md),
[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-requirement-level.md),
and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/metric-requirement-level.md) conventions.

Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.17.0/semantic-conventions/syntax.md)
for how to write the YAML files for semantic conventions and what the YAML properties mean.
Expand Down
3 changes: 3 additions & 0 deletions specification/document-status.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Document Status

Semantic Conventions follows the [Specification document status conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md).
2 changes: 1 addition & 1 deletion specification/logs/semantic_conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@ The following semantic conventions for events are defined:
* [Events](events.md): Semantic attributes that must be used to represent Events using log data model.

Apart from semantic conventions for logs, [traces](../../trace/semantic_conventions/README.md), and [metrics](../../metrics/semantic_conventions/README.md),
OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own
OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) with their own
[Resource Semantic Conventions](../../resource/semantic_conventions/README.md).
8 changes: 4 additions & 4 deletions specification/logs/semantic_conventions/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
**Status**: [Experimental](../../document-status.md)

This document defines semantic conventions for recording exceptions on
[logs](../bridge-api.md#emit-a-logrecord) and [events](../event-api.md#emit-event)
emitted through the [Logger API](../bridge-api.md#logger).
[logs](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md#emit-event)
emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logger).

<!-- toc -->

Expand All @@ -17,7 +17,7 @@ emitted through the [Logger API](../bridge-api.md#logger).
## Recording an Exception

Exceptions SHOULD be recorded as attributes on the
[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logger) emit
operations. Exceptions MAY be recorded on "logs" or "events" depending on the
context.

Expand All @@ -29,7 +29,7 @@ the language runtime.
## Attributes

The table below indicates which attributes should be added to the
[LogRecord](../data-model.md#log-and-event-record-definition) and their types.
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) and their types.

<!-- semconv log-exception -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand Down
8 changes: 4 additions & 4 deletions specification/logs/semantic_conventions/feature-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
**Status**: [Experimental](../../document-status.md)

This document defines semantic conventions for recording feature flag evaluations as
a [log record](../data-model.md#log-and-event-record-definition) emitted through the
[Logger API](../bridge-api.md#emit-a-logrecord).
a [log record](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) emitted through the
[Logger API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#emit-a-logrecord).
This is useful when a flag is evaluated outside of a transaction context
such as when the application loads or on a timer.
To record a flag evaluation as a part of a transaction context,
Expand All @@ -24,14 +24,14 @@ section of the trace semantic convention for feature flag evaluations.
## Recording an Evaluation

Feature flag evaluations SHOULD be recorded as attributes on the
[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logger) emit
operations. Evaluations MAY be recorded on "logs" or "events" depending on the
context.

## Attributes

The table below indicates which attributes should be added to the
[LogRecord](../data-model.md#log-and-event-record-definition) and their types.
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#log-and-event-record-definition) and their types.

<!-- semconv log-feature_flag -->
The event name MUST be `feature_flag`.
Expand Down
2 changes: 1 addition & 1 deletion specification/logs/semantic_conventions/media.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This document describes attributes for log media in OpenTelemetry. Log media are

## Log Media

**Note:** The OpenTelemetry specification defines a [Resource](../../resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`.
**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`.
The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission.
As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes.

Expand Down
42 changes: 42 additions & 0 deletions specification/metrics/metric-requirement-level.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Metric Requirement Levels

This document is the same as [the specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/metric-requirement-level.md).
jsuereth marked this conversation as resolved.
Show resolved Hide resolved

**Status**: [Stable](../document-status.md)

<details>
<summary>Table of Contents</summary>

<!-- toc -->

- [Required](#required)
- [Recommended](#recommended)
- [Opt-In](#opt-in)

<!-- tocstop -->

</details>

The following metric requirement levels are specified:

- [Required](#required)
- [Recommended](#recommended)
- [Opt-In](#opt-in)

## Required

All instrumentations MUST emit the metric.
A semantic convention defining a Required metric expects that an absolute majority of instrumentation libraries and applications are able to efficiently emit it.

## Recommended

Instrumentations SHOULD emit the metric by default if it's readily available and can be efficiently emitted. Instrumentations MAY offer a configuration option to disable Recommended metrics.

Instrumentations that decide not to emit `Recommended` metrics due to performance, security, privacy, or other consideration by default, SHOULD allow for opting in to emitting them as defined for the `Opt-In` requirement level if the metrics are logically applicable.

## Opt-In

Instrumentations SHOULD emit the metric if and only if the user configures the instrumentation to do so.
Instrumentation that doesn't support configuration MUST NOT emit `Opt-In` metrics.

This attribute requirement level is recommended for metrics that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled deliberately by a user making an informed decision.
4 changes: 2 additions & 2 deletions specification/metrics/semantic_conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The following semantic conventions surrounding metrics are defined:

Apart from semantic conventions for metrics and
[traces](../../trace/semantic_conventions/README.md), OpenTelemetry also
defines the concept of overarching [Resources](../../resource/sdk.md) with
defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) with
their own [Resource Semantic
Conventions](../../resource/semantic_conventions/README.md).

Expand Down Expand Up @@ -97,7 +97,7 @@ usable.

When building components that interoperate between OpenTelemetry and a system
using the OpenMetrics exposition format, use the
[OpenMetrics Guidelines](../../compatibility/prometheus_and_openmetrics.md).
[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md).

### Pluralization

Expand Down
8 changes: 4 additions & 4 deletions specification/metrics/semantic_conventions/http-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
Expand Down Expand Up @@ -119,7 +119,7 @@ This metric is optional.
| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

**[1]:** Determined by using the first of the following that applies

Expand Down Expand Up @@ -161,7 +161,7 @@ This metric is optional.
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
Expand Down Expand Up @@ -208,7 +208,7 @@ This metric is optional.
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
# Instrumentation

Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ This metric is obtained by subscribing to
[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--)

This metric SHOULD be specified with
[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advice)
[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice)
of `[]` (single bucket histogram capturing count, sum, min, max).

<!-- semconv metric.process.runtime.jvm.gc.duration(metric_table) -->
Expand Down
8 changes: 4 additions & 4 deletions specification/resource/semantic_conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**Status**: [Mixed](../../document-status.md)

This document defines standard attributes for resources. These attributes are typically used in the [Resource](../sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
[OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md).

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
Expand Down Expand Up @@ -40,7 +40,7 @@ This document defines standard attributes for resources. These attributes are ty

Attributes are grouped logically by the type of the concept that they described. Attributes in the same group have a common prefix that ends with a dot. For example all attributes that describe Kubernetes properties start with "k8s."

See [Attribute Requirement Levels](../../common/attribute-requirement-level.md) for details on when attributes
See [Attribute Requirement Levels](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-requirement-level.md) for details on when attributes
should be included.

## Attributes with Special Handling
Expand All @@ -52,14 +52,14 @@ Given their significance some resource attributes are treated specifically as de
### Semantic Attributes with Dedicated Environment Variable

These are the attributes which MAY be configurable via a dedicated environment variable
as specified in [OpenTelemetry Environment Variable Specification](../../configuration/sdk-environment-variables.md):
as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md):

- [`service.name`](#service)

## 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](../sdk.md#sdk-provided-resource-attributes):
as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#sdk-provided-resource-attributes):

- [`service.name`](#service)
- [`telemetry.sdk` group](#telemetry-sdk)
Expand Down
Loading