Skip to content

Commit c33919e

Browse files
reyangreyang
authored
DocFX sanity check (open-telemetry#742)
1 parent de3b65e commit c33919e

File tree

19 files changed

+121
-57
lines changed

19 files changed

+121
-57
lines changed

‎.github/workflows/docfx.yml

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: docfx
2+
3+
on:
4+
pull_request:
5+
branches: [ master ]
6+
7+
jobs:
8+
build:
9+
runs-on: windows-latest
10+
11+
steps:
12+
- name: check out code
13+
uses: actions/checkout@v2
14+
15+
- name: install docfx
16+
run: choco install docfx -y
17+
18+
- name: run .\docfx.cmd
19+
shell: cmd
20+
run: .\docfx.cmd

‎README.md

+5-6
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ The OpenTelemetry specification describes the cross-language requirements and ex
1212
- [Glossary](specification/glossary.md)
1313
- [Library Guidelines](specification/library-guidelines.md)
1414
- [Package/Library Layout](specification/library-layout.md)
15-
- [Concurrency and Thread-Safety](specification/concurrency.md)
1615
- API Specification
1716
- [CorrelationContext](specification/correlationcontext/api.md)
1817
- [Propagators](specification/context/api-propagators.md)
@@ -23,7 +22,7 @@ The OpenTelemetry specification describes the cross-language requirements and ex
2322
- [Resource](specification/resource/sdk.md)
2423
- [Configuration](specification/sdk-configuration.md)
2524
- Data Specification
26-
- [Semantic Conventions](specification/overview.md#semantic-conventions.md)
25+
- [Semantic Conventions](specification/overview.md#semantic-conventions)
2726
- [Protocol](specification/protocol/README.md)
2827
- About the Project
2928
- [Timeline](#project-timeline)
@@ -43,14 +42,14 @@ Information about current work and future development plans is found at the
4342

4443
## Notation Conventions and Compliance
4544

46-
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the [specification](./specification) are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [[RFC2119](https://tools.ietf.org/html/rfc2119)] [[RFC8174](https://tools.ietf.org/html/rfc8174)] when, and only when, they appear in all capitals, as shown here.
45+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the [specification](./specification/overview.md) are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [[RFC2119](https://tools.ietf.org/html/rfc2119)] [[RFC8174](https://tools.ietf.org/html/rfc8174)] when, and only when, they appear in all capitals, as shown here.
4746

48-
An implementation of the [specification](./specification) is not compliant if it fails to satisfy one or more of the "MUST", "MUST NOT", "REQUIRED", "SHALL", or "SHALL NOT" requirements defined in the [specification](./specification).
49-
Conversely, an implementation of the [specification](./specification) is compliant if it satisfies all the "MUST", "MUST NOT", "REQUIRED", "SHALL", and "SHALL NOT" requirements defined in the [specification](./specification).
47+
An implementation of the [specification](./specification/overview.md) is not compliant if it fails to satisfy one or more of the "MUST", "MUST NOT", "REQUIRED", "SHALL", or "SHALL NOT" requirements defined in the [specification](./specification/overview.md).
48+
Conversely, an implementation of the [specification](./specification/overview.md) is compliant if it satisfies all the "MUST", "MUST NOT", "REQUIRED", "SHALL", and "SHALL NOT" requirements defined in the [specification](./specification/overview.md).
5049

5150
## Versioning
5251

53-
Changes to the [specification](./specification) are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [CHANGELOG.md](CHANGELOG.md). Layout changes are not versioned. Specific implementations of the specification should specify which version they implement.
52+
Changes to the [specification](./specification/overview.md) are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [CHANGELOG.md](CHANGELOG.md). Layout changes are not versioned. Specific implementations of the specification should specify which version they implement.
5453

5554
Changes to the change process itself are not currently versioned but may be independently versioned in the future.
5655

‎docfx.cmd

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
SETLOCAL
2+
SETLOCAL ENABLEEXTENSIONS
3+
4+
docfx.exe build docfx.json > docfx.log
5+
@IF NOT %ERRORLEVEL% == 0 (
6+
type docfx.log
7+
ECHO Error: docfx build failed. 1>&2
8+
EXIT /B %ERRORLEVEL%
9+
)
10+
@type docfx.log
11+
@type docfx.log | findstr /C:"Build succeeded."
12+
@IF NOT %ERRORLEVEL% == 0 (
13+
ECHO Error: you have introduced build warnings. 1>&2
14+
EXIT /B %ERRORLEVEL%
15+
)

‎docfx.json

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"build": {
3+
"content": [
4+
{
5+
"files": [
6+
"**.md",
7+
"toc.yml"
8+
]
9+
}
10+
],
11+
"resource": [
12+
{
13+
"files": [
14+
".markdownlint.yaml",
15+
".vscode/settings.json",
16+
"**.png"
17+
]
18+
}
19+
],
20+
"dest": "_site",
21+
"globalMetadataFiles": [],
22+
"fileMetadataFiles": [],
23+
"noLangKeyword": false,
24+
"keepFileLink": false,
25+
"cleanupCacheHistory": true,
26+
"disableGitFeatures": true
27+
}
28+
}

‎specification/common/common.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Table of Contents
66
</summary>
77

8-
- [Attributes](#attribute)
8+
- [Attributes](#attributes)
99

1010
</details>
1111

‎specification/context/api-propagators.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ Table of Contents
1414
- [HTTPText Propagator](#httptext-propagator)
1515
- [Fields](#fields)
1616
- [Inject](#inject-1)
17-
- [Setter argument](#setter)
17+
- [Setter argument](#setter-argument)
1818
- [Set](#set)
1919
- [Extract](#extract-1)
20-
- [Getter argument](#getter)
20+
- [Getter argument](#getter-argument)
2121
- [Get](#get)
2222
- [Composite Propagator](#composite-propagator)
2323
- [Global Propagators](#global-propagators)

‎specification/context/context.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Table of Contents
99
- [Create a key](#create-a-key)
1010
- [Get value](#get-value)
1111
- [Set value](#set-value)
12-
- [Optional operations](#optional-operations)
12+
- [Optional global operations](#optional-global-operations)
1313
- [Get current Context](#get-current-context)
1414
- [Attach Context](#attach-context)
1515
- [Detach Context](#detach-context)

‎specification/glossary.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ Synonyms: *Instrumenting Library*.
6464
### Tracer Name / Meter Name
6565

6666
This refers to the `name` and (optional) `version` arguments specified when
67-
creating a new `Tracer` or `Meter` (see [Obtaining a Tracer](trace/api.md#obtaining-a-tracer)/[Obtaining a Meter](metrics/api.md#meter-interface)).
67+
creating a new `Tracer` or `Meter` (see [Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meter-interface)).
6868
The name/version pair identifies the [Instrumentation Library](#instrumentation-library).
6969

7070
## Logs

‎specification/library-guidelines.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,8 @@ guidelines on the performance expectations that API implementations should meet,
119119

120120
### Concurrency and Thread-Safety
121121

122-
See the [Concurrency and Thread-Safety](concurrency.md) specification for
123-
guidelines on what concurrency safeties should API implementations provide
124-
and how they should be documented.
122+
Please refer to individual API specification for guidelines on what concurrency
123+
safeties should API implementations provide and how they should be documented:
124+
125+
* [Metrics API](./metrics/api.md#concurrency)
126+
* [Tracing API](./trace/api.md#concurrency)

‎specification/metrics/api.md

+16-18
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
- [Meter provider](#meter-provider)
1414
* [Obtaining a Meter](#obtaining-a-meter)
1515
* [Global Meter provider](#global-meter-provider)
16-
+ [Get the global MeterProvider](#get-the-global-metricprovider)
17-
+ [Set the global MeterProvider](#set-the-global-metricprovider)
16+
+ [Get the global MeterProvider](#get-the-global-meterprovider)
17+
+ [Set the global MeterProvider](#set-the-global-meterprovider)
1818
- [Instrument properties](#instrument-properties)
1919
* [Instrument naming requirements](#instrument-naming-requirements)
2020
* [Synchronous and asynchronous instruments compared](#synchronous-and-asynchronous-instruments-compared)
@@ -32,7 +32,6 @@
3232
* [Constructors](#constructors)
3333
- [Sets of labels](#sets-of-labels)
3434
* [Label performance](#label-performance)
35-
* [Missing label keys](#missing-label-keys)
3635
* [Option: Ordered labels](#option-ordered-labels)
3736
- [Synchronous instrument details](#synchronous-instrument-details)
3837
* [Synchronous calling conventions](#synchronous-calling-conventions)
@@ -82,14 +81,13 @@ understand their meaning. Standard implementations perform
8281
aggregation corresponding to the default interpretation for each kind
8382
of metric event.
8483

85-
Monitoring and alerting systems commonly use the data provided through
86-
metric events, after applying various [aggregations](#aggregations)
87-
and converting into various [exposition formats](#exposition-formats).
88-
However, we find that there are many other uses for metric events,
89-
such as to record aggregated or raw measurements in tracing and
90-
logging systems. For this reason, [OpenTelemetry requires a
91-
separation of the API from the SDK](../library-guidelines.md#requirements),
92-
so that different SDKs can be configured at run time.
84+
Monitoring and alerting systems commonly use the data provided through metric
85+
events, after applying various [aggregations](#aggregations) and converting into
86+
various exposition formats. However, we find that there are many other uses for
87+
metric events, such as to record aggregated or raw measurements in tracing and
88+
logging systems. For this reason, [OpenTelemetry requires a separation of the
89+
API from the SDK](../library-guidelines.md#requirements), so that different SDKs
90+
can be configured at run time.
9391

9492
### Measurements
9593

@@ -215,13 +213,13 @@ provider interface, or other language-specific support. Note that it
215213
is not necessary to use the global instance: multiple instances of the
216214
OpenTelemetry SDK may run simultaneously.
217215

218-
As an obligatory step, the API requires the caller to provide the name
219-
of the instrumenting library (optionally, the version) when obtaining
220-
a `Meter` implementation. The library name is meant to be used for
221-
identifying instrumentation produced from that library, for such
222-
purposes as disabling instrumentation, configuring aggregation, and
223-
applying sampling policies. See the specification on [obtaining a
224-
Tracer](../trace/api.md#obtaining-a-tracer) for more details.
216+
As an obligatory step, the API requires the caller to provide the name of the
217+
instrumenting library (optionally, the version) when obtaining a `Meter`
218+
implementation. The library name is meant to be used for identifying
219+
instrumentation produced from that library, for such purposes as disabling
220+
instrumentation, configuring aggregation, and applying sampling policies. See
221+
the specification on [TracerProvider](../trace/api.md#tracerprovider) for more
222+
details.
225223

226224
### Aggregations
227225

‎specification/performance.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Here are the key principles:
1111

1212
Although there are inevitable overhead to achieve monitoring, API should not degrade the end-user application as possible. So that it should not block the end-user application nor consume too much memory resource.
1313

14-
See also [Concurrency and Thread-Safety](concurrency.md) if the implementation supports concurrency.
14+
See also [Concurrency and Thread-Safety](library-guidelines.md#concurrency-and-thread-safety) if the implementation supports concurrency.
1515

1616
### Tradeoff between non-blocking and memory consumption
1717

‎specification/resource/sdk.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ with closed source environments. The SDK MUST allow for creation of `Resources`
1313
for associating them with telemetry.
1414

1515
When used with distributed tracing, a resource can be associated with the
16-
[TracerProvider](../trace/sdk.md#tracer-sdk) when it is created.
16+
[TracerProvider](../trace/api.md#tracerprovider) when it is created.
1717
That association cannot be changed later.
1818
When associated with a `TracerProvider`,
1919
all `Span`s produced by any `Tracer` from the provider MUST be associated with this `Resource`.

‎specification/resource/semantic_conventions/faas.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
|---|---|---|--|
99
| faas.name | The name of the function being executed. | `my-function` | Yes |
1010
| faas.id | The unique name of the function being executed. <br /> For example, in AWS Lambda this field corresponds to the [ARN] value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory] field. | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes |
11-
| faas.version | The version string of the function being executed as defined in [Version Attributes](#version-attributes). | `semver:2.0.0` | No |
11+
| faas.version | The version string of the function being executed as defined in [Version Attributes](./README.md#version-attributes) | `semver:2.0.0` | No |
1212
| faas.instance | The execution environment ID as a string. | `my-function:instance-0001` | No |
1313

1414
Note: The resource attribute `faas.instance` differs from the span attribute `faas.execution`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-execution-and-instance).

‎specification/resource/semantic_conventions/host.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,4 @@
1212
| host.type | Type of host.<br/> For Cloud this must be the machine type.| `n1-standard-1` |
1313
| host.image.name | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`, `CentOS-8-x86_64-1905` |
1414
| host.image.id | VM image id. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` |
15-
| host.image.version | The version string of the VM image as defined in [Version Attributes](#version-attributes). | `0.1` |
15+
| host.image.version | The version string of the VM image as defined in [Version Attributes](./README.md#version-attributes). | `0.1` |

‎specification/trace/api.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,9 @@ Table of Contents
99
* [Time](#time)
1010
* [Timestamp](#timestamp)
1111
* [Duration](#duration)
12+
* [TracerProvider](#tracerprovider)
13+
* [TracerProvider operations](#tracerprovider-operations)
1214
* [Tracer](#tracer)
13-
* [Obtaining a tracer](#obtaining-a-tracer)
1415
* [Tracer operations](#tracer-operations)
1516
* [SpanContext](#spancontext)
1617
* [Span](#span)
@@ -106,7 +107,7 @@ That API MUST accept the following parameters:
106107
functionality (e.g. an implementation which is not even observability-related).
107108
A TracerProvider could also return a no-op Tracer here if application owners configure
108109
the SDK to suppress telemetry produced by this library.
109-
- `version` (optional): Specifies the [version](../resource/semantic_conventions#version-attributes) of the instrumentation library
110+
- `version` (optional): Specifies the [version](../resource/semantic_conventions/README.md#version-attributes) of the instrumentation library
110111
(e.g. `semver:1.0.0`).
111112

112113
It is unspecified whether or under which conditions the same or different
@@ -334,7 +335,7 @@ description](../overview.md#links-between-spans).
334335
A `Link` is defined by the following properties:
335336

336337
- (Required) `SpanContext` of the `Span` to link to.
337-
- (Optional) One or more `Attribute`s as defined [here](../).
338+
- (Optional) One or more `Attribute`s as defined [here](../common/common.md#attributes).
338339

339340
The `Link` SHOULD be an immutable type.
340341

‎specification/trace/sdk.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,8 @@ The flag combination `SampledFlag == true` and `IsRecording == false`
4444
could cause gaps in the distributed trace, and because of this OpenTelemetry API
4545
MUST NOT allow this combination.
4646

47-
The SDK defines the two interfaces [`Sampler`](#sampler) and
48-
[`Decision`](#decision) as well as a set of [built-in
49-
samplers](#built-in-samplers).
47+
The SDK defines the interface [`Sampler`](#sampler) as well as a set of
48+
[built-in samplers](#built-in-samplers).
5049

5150
### Sampler
5251

‎specification/trace/sdk_exporters/zipkin.md

+14-14
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,21 @@ Zipkin's v2 API is defined in the
99
The following table summarizes the major transformations between OpenTelemetry
1010
and Zipkin.
1111

12-
| OpenTelemetry | Zipkin | Notes |
13-
| ------------------------ | ---------------- | ------------------------------------------------------------ |
14-
| Span.TraceID | Span.TraceID | |
15-
| Span.ParentID | Span.ParentID | |
16-
| Span.SpanID | Span.ID | |
17-
| Span.TraceState | TBD | TBD |
18-
| Span.Name | Span.Name | |
19-
| Span.Kind | Span.Kind | See [SpanKind](#spankind) for values mapping |
20-
| Span.StartTime | Span.Timestamp | See [Unit of time](#unit-of-time) |
12+
| OpenTelemetry | Zipkin | Notes |
13+
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------- |
14+
| Span.TraceID | Span.TraceID | |
15+
| Span.ParentID | Span.ParentID | |
16+
| Span.SpanID | Span.ID | |
17+
| Span.TraceState | TBD | TBD |
18+
| Span.Name | Span.Name | |
19+
| Span.Kind | Span.Kind | See [SpanKind](#spankind) for values mapping |
20+
| Span.StartTime | Span.Timestamp | See [Unit of time](#unit-of-time) |
2121
| Span.EndTime | Span.Duration | Duration is calculated based on StartTime and EndTime. See also [Unit of time](#unit-of-time) |
22-
| Span.Attributes | Span.Tags | See [Attributes](#attributes) for data types for the mapping. |
23-
| Span.Events | Span.Annotations | See [Events](#events) for the mapping format. |
24-
| Span.Links | TBD | TBD |
25-
| Span.Status | Add to Span.Tags | See [Status](#status) for tag names to use. |
26-
| Span.LocalChildSpanCount | TBD | TBD |
22+
| Span.Attributes | Span.Tags | See [Attributes](../../common/common.md#attributes) for data types for the mapping. |
23+
| Span.Events | Span.Annotations | See [Events](#events) for the mapping format. |
24+
| Span.Links | TBD | TBD |
25+
| Span.Status | Add to Span.Tags | See [Status](#status) for tag names to use. |
26+
| Span.LocalChildSpanCount | TBD | TBD |
2727

2828
TBD : This is work in progress document and it is currently doesn't specify
2929
mapping for these fields:

‎specification/trace/semantic_conventions/faas.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ This document defines how to describe an instance of a function that runs withou
2121

2222
Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section.
2323

24-
If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../../resource/semantic_conventions/README.md#function-as-a-service).
24+
If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../../resource/semantic_conventions/faas.md#function-as-a-service).
2525

2626
| Attribute name | Notes and examples | Required? |
2727
|---|---|--|

‎toc.yml

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
- name: OpenTelemetry Specification
2+
href: ./README.md

0 commit comments

Comments
 (0)