Fix lint check in makefile, fix errors (open-telemetry#837)

Signed-off-by: Bogdan Drutu <[email protected]>

Makefile

@@ -1,5 +1,5 @@
 # All documents to be used in spell check.
-ALL_DOCS := $(shell find . -name '*.md' -type f | grep -v ^./node_modules | sort)
+ALL_DOCS := $(shell find . -name '*.md' -not -path './.github/*' -type f | grep -v ^./node_modules | sort)
 
 TOOLS_DIR := ./.tools
 MISSPELL_BINARY=$(TOOLS_DIR)/misspell
@@ -32,4 +32,5 @@ install-markdown-lint:
 
 .PHONY: markdown-lint
 markdown-lint:
-	@for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f; done
+	@echo $(ALL_DOCS)
+	@for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f || exit 1;	done

experimental/metrics/config-service.md

@@ -20,8 +20,8 @@
 
 <small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
 
-
 ## Overview
+
 The OpenTelemetry Metric Configuration Service adds the ability to dynamically
 and remotely configure metric collection schedules. A user may specify
 collection periods at runtime, and propagate these changes to instrumented
@@ -35,8 +35,8 @@ third-party metric provider has an existing metric configuration service (or
 would like to implement one in the future), and if it communicates using this
 protocol, it may speak directly with our instrumented applications.
 
-
 ## Service Protocol
+
 Configuration data is communicated between an SDK and a backend (either directly
 or indirectly through a Collector) using the following protocol specification.
 The SDK is assumed to be the client, and makes the metric config requests. The
@@ -45,6 +45,7 @@ responses. For more details on this arrangement, see
 [below](#push-vs-pull-metric-model).
 
 ### Metric Config Request
+
 A request consists of two fields: `resource` and an optional
 `last_known_fingerprint`.
 
@@ -63,10 +64,12 @@ If unspecified, the configuration backend will send the full schedules with each
 request.
 
 ### Metric Config Response
+
 A response consists of three fields `schedules`, `fingerprint`, and
 `suggested_wait_time_sec`.
 
 #### Schedules
+
 `schedules` is a list of metric schedules. Each schedule consists of three
 components: `exclusion_patterns`, `inclusion_patterns`, and `period_sec`.
 
@@ -85,6 +88,7 @@ periods that are divisible by the smallest period (see
 collected
 
 #### Fingerprint
+
 `fingerprint` is a sequence of bytes that corresponds to the set of schedules
 being sent. There are two requirements on computing fingerprints:
 
@@ -97,12 +101,14 @@ is the same as the response’s `last_known_fingerprint`, then all other fields
 the response are optional.
 
 #### Wait Time
+
 `suggested_wait_time_sec` is a duration (in seconds) that the SDK should wait
 before sending the next metric config request. A response MAY have a
 `suggested_wait_time_sec`, but its use is optional, and the SDK need not obey
 it. As the name implies, it is simply a suggestion.
 
 ### Push vs Pull Metric Model
+
 Note that the configuration service assumes a “push” model of metric export --
 that is, metrics are pushed from the SDK to a receiving backend. The backend
 serves incoming requests that contain metric data. This is in contrast to the
@@ -114,8 +120,8 @@ metrics, and the need for our configuration service is less relevant. We
 therefore assume that all systems using the configuration service deliver
 metrics on a push-based model.
 
-
 ## Implementation Details
+
 Because this specification is experimental, and may imply substantial changes to
 the existing system, we provide additional details on the example prototype
 implementations available on the
@@ -125,6 +131,7 @@ actual implementation in an SDK will likely differ. We offer these details not
 as formal specification, but as an example of how this system might look.
 
 ### Collection Periods
+
 Though the protocol does not enforce specific collection periods, the SDK MAY
 assume that all larger collection periods will be divisible by the smallest
 period in a set of schedules, for the sake of optimization. Indeed, it is
@@ -149,6 +156,7 @@ However, the SDK MUST still be able to handle periods of any nonzero integer
 duration, even if they violate the divisibility suggestion.
 
 ### Go SDK
+
 A prototype implementation of metric configuration is available for the Go SDK,
 currently hosted on the [contrib repo](https://github.com/vmingchen/opentelemetry-go-contrib). It provides an
 alternative push controller component with the ability to configure collection
@@ -166,6 +174,7 @@ controller, in place of OpenTelemetry’s version, to be able to have access to
 this feature.
 
 ### Collector Extension
+
 An example configuration backend is implemented as an extension for the
 Collector, currently hosted on the [contrib repo](https://github.com/vmingchen/opentelemetry-collector-contrib). When this extension is enabled, the Collector
 functions as a potential endpoint for Agent/SDKs to retrieve configuration data.
@@ -184,6 +193,7 @@ The configuration data itself may be specified using one of two sources: a local
 file or a connection to a remote backend.
 
 #### Local File
+
 Configuration data can be specified in the form of a local file that the
 collector monitors. Changes to the file are immediately reflected in the
 Collector’s in-memory representation of the data, so there is no need to restart
@@ -213,6 +223,7 @@ ConfigBlocks:
 ```
 
 The following rules govern the file-based configurations:
+
 * There MUST be 1 ConfigBlock or more in a ConfigBlocks list
 * Each ConfigBlock MAY have a field Resource
 * Resource MAY have one or more strings, each a string-representation of a key-value label in a resource. If no strings are specified, then this ConfigBlock matches with any request
@@ -222,6 +233,7 @@ The following rules govern the file-based configurations:
 * Each Schedule MUST have a field Period, corresponding to the collection period of the metrics matched by this Schedule
 
 ##### Matching Behavior
+
 An incoming request specifies a resource for which configuration data should be
 returned. A ConfigBlock matches a resource if all strings listed under
 ConfigBlock::Resource exactly equal a key-value label in the resource. In the
@@ -236,11 +248,13 @@ across telemetry sources, unless superseded by a more specific ConfigBlock that
 asks for a shorter period.
 
 ##### Fingerprint Hashing
+
 Fingerprints are generated using an FNVa 64 bit hashing scheme. The hash is
 uniquely determined by the contents of a ConfigBlock. The order of patterns and
 the order of schedules do not impact the resulting hash.
 
 #### Remote Backend
+
 Alternatively, instead of using a local file, the Collector may use another
 configuration service backend. This remote backend could be another Collector,
 or it could be a third party that implements the configuration service. In the

specification/common/common.md

@@ -7,6 +7,7 @@ Table of Contents
 
 - [Attributes](#attributes)
   - [Attribute and Label Naming](#attribute-and-label-naming)
+
 </details>
 
 ## Attributes
@@ -130,4 +131,3 @@ It is recommended to limit names to printable Basic Latin characters
 (more precisely to
 [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
 subset of Unicode code points).
-

specification/correlationcontext/api.md

@@ -136,4 +136,3 @@ otcorrelations: user=foo%40example.com,name=Example%20Name
 
 If a new name/value pair is added and its name is the same as an existing name, than the new pair MUST take precedence. The value
 is replaced with the added value (regardless if it is locally generated or received from a remote peer).
-

specification/error-handling.md

@@ -56,28 +56,27 @@ SDKs MAY expose callbacks to allow end users to handle self-diagnostics separate
 
 SDK implementations MUST allow end users to change the library's default error handling behavior for relevant errors.
 Application developers may want to run with strict error handling in a staging environment to catch invalid uses of the API, or malformed config.
-Note that configuring a custom error handler in this way is the only exception to the basic error handling principles outlined above. 
-The mechanism by which end users set or register a custom error handler should follow language-specific conventions. 
+Note that configuring a custom error handler in this way is the only exception to the basic error handling principles outlined above.
+The mechanism by which end users set or register a custom error handler should follow language-specific conventions.
 
-### Examples 
+### Examples
 
-These are examples of how end users might register custom error handlers. 
+These are examples of how end users might register custom error handlers.
 Examples are for illustration purposes only. Language library authors
-are free to deviate from these provided that their design matches the requirements outlined above. 
+are free to deviate from these provided that their design matches the requirements outlined above.
 
-##### Go
+#### Go
 
 ```go
 // The basic Error Handler interface
 type ErrorHandler interface {
-	Handle(err error)
+  Handle(err error)
 }
 
 func Handler() ErrorHandler
 func SetHandler(handler ErrorHandler)
 ```
 
-
 ```go
 // Registering a custom Error Handler
 type IgnoreExporterErrorsHandler struct{}
@@ -91,7 +90,7 @@ func (IgnoreExporterErrorsHandler) Handle(err error) {
 }
 
 func main() {
-    // Other setup ... 
+    // Other setup ...
     opentelemetrysdk.SetHandler(IgnoreExporterErrorsHandler{})
 }
 
@@ -100,11 +99,10 @@ func main() {
 ##### Java
 
 OpenTelemetry Java uses [java.util.logging](https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html)
-to output and handle all logs, including errors. Custom handlers and filters can be registered both in code and using the 
-Java logging configuration file.  
+to output and handle all logs, including errors. Custom handlers and filters can be registered both in code and using the Java logging configuration file.  
 
 ```properties
-## Turn off all error logging 
+## Turn off all error logging
 io.opentelemetry.level = OFF
 ```
 

specification/glossary.md

@@ -30,6 +30,7 @@ Some other fundamental terms are documented in the [overview document](overview.
 
 <a name="in-band"></a>
 <a name="out-of-band"></a>
+
 ### In-band and Out-of-band Data
 
 > In telecommunications, **in-band signaling** is the sending of control information within the same band or channel used for data such as voice or video. This is in contrast to **out-of-band signaling** which is sent over a different channel, or even over a separate network ([Wikipedia](https://en.wikipedia.org/wiki/In-band_signaling)).
@@ -46,15 +47,13 @@ usually asynchronously by background routines
 rather than from the critical path of the business logic.
 Metrics, logs, and traces exported to telemetry backends are examples of out-of-band data.
 
-<a name="telemetry_sdk"></a>
 ### Telemetry SDK
 
 Denotes the library that implements the *OpenTelemetry API*.
 
 See [Library Guidelines](library-guidelines.md#sdk-implementation) and
 [Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk).
 
-<a name="exporter_library"></a>
 ### Exporter Library
 
 Libraries which are compatible with the [Telemetry SDK](#telemetry-sdk) and provide functionality to emit telemetry to consumers.
@@ -68,8 +67,6 @@ or by another [Instrumentation Library](#instrumentation-library).
 
 Example: `org.mongodb.client`.
 
-<a name="instrumenting_library"></a>
-<a name="instrumentation_library"></a>
 ### Instrumentation Library
 
 Denotes the library that provides the instrumentation for a given [Instrumented Library](#instrumented-library).
@@ -82,8 +79,6 @@ Example: `io.opentelemetry.contrib.mongodb`.
 
 Synonyms: *Instrumenting Library*.
 
-<a name="tracer-name"></a>
-<a name="meter-name"></a>
 ### Tracer Name / Meter Name
 
 This refers to the `name` and (optional) `version` arguments specified when

specification/logs/overview.md

@@ -411,7 +411,7 @@ standard output.
 ## Trace Context in Legacy Formats
 
 Earlier we briefly mentioned that it is possible to modify existing applications
-so that they include the Request Context information in the emitted logs. 
+so that they include the Request Context information in the emitted logs.
 
 [OTEP0114](https://github.com/open-telemetry/oteps/pull/114) defines how the
 trace context should be recorded in logs. To summarize, the following field
@@ -425,9 +425,7 @@ names should be used in legacy formats:
 All 3 fields are optional (see the [data model](data-model.md) for details of
 which combination of fields is considered valid).
 
-Here are examples for some legacy formats:
-
-**Syslog RFC5424**
+### Syslog RFC5424
 
 Trace id, span id and traceflags SHOULD be recorded via SD-ID "opentelemetry".
 
@@ -437,7 +435,7 @@ For example:
 [opentelemetry traceid="102981ABCD2901" spanid="abcdef1010" traceflags="01"]
 ```
 
-**Plain Text Formats**
+### Plain Text Formats
 
 The fields should be recorded according to the customary approach used for a
 particular format (e.g. field:value format for LTSV). For example:
@@ -446,7 +444,7 @@ particular format (e.g. field:value format for LTSV). For example:
 host:192.168.0.1<TAB>traceid:102981ABCD2901<TAB>spanid:abcdef1010<TAB>time:[01/Jan/2010:10:11:23 -0400]<TAB>req:GET /health HTTP/1.0<TAB>status:200
 ```
 
-**JSON Formats**
+### JSON Formats
 
 The fields should be recorded as top-level fields in the JSON structure. For example:
 
@@ -459,7 +457,7 @@ The fields should be recorded as top-level fields in the JSON structure. For exa
 }
 ```
 
-***Other Structured Formats***
+### Other Structured Formats
 
 The fields should be recorded as top-level structured attributes of the log
 record as it is customary for the particular format.

specification/overview.md

@@ -306,7 +306,7 @@ Vision](https://github.com/open-telemetry/opentelemetry-collector/blob/master/do
 
 ## Instrumentation Libraries
 
-See [Instrumentation Library](glossary.md#instrumentation_library)
+See [Instrumentation Library](glossary.md#instrumentation-library)
 
 The inspiration of the project is to make every library and application
 observable out of the box by having them call OpenTelemetry API directly. However,
@@ -316,7 +316,7 @@ wrapping interfaces, subscribing to library-specific callbacks, or translating
 existing telemetry into the OpenTelemetry model.
 
 A library that enables OpenTelemetry observability for another library is called
-an [Instrumentation Library](glossary.md#instrumentation_library).
+an [Instrumentation Library](glossary.md#instrumentation-library).
 
 An instrumentation library should be named to follow any naming conventions of
 the instrumented library (e.g. 'middleware' for a web framework).

specification/protocol/exporter.md

@@ -52,9 +52,10 @@ export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http
 
 ## Retry
 
-[Transient errors](#transient-errors) MUST be handled with a retry strategy. This retry strategy MUST implement an exponential back-off with jitter to avoid overwhelming the destination until the network is restored or the destination has recovered. 
+[Transient errors](#transient-errors) MUST be handled with a retry strategy. This retry strategy MUST implement an exponential back-off with jitter to avoid overwhelming the destination until the network is restored or the destination has recovered.
 
 ## Transient Errors
+
 Transient errors are errors which expect the backend to recover. The following status codes are defined as transient errors:
 
 | HTTP Status Code | Description |

specification/trace/api.md

@@ -226,7 +226,6 @@ That is, "get_user" is a reasonable name, while "get_user/314159",
 where "314159" is a user ID, is not a good name due to its high cardinality.
 Generality SHOULD be prioritized over human-readability.
 
-
 For example, here are potential span names for an endpoint that gets a
 hypothetical account information:
 
@@ -421,7 +420,6 @@ Note that [Samplers](sdk.md#sampler) can only consider information already
 present during span creation. Any changes done later, including new or changed
 attributes, cannot change their decisions.
 
-
 #### Add Events
 
 A `Span` MUST have the ability to add events. Events have a time associated

specification/trace/sdk.md

@@ -96,7 +96,7 @@ Description MUST NOT change over time and caller can cache the returned value.
 
 ### Built-in samplers
 
-OpenTelemetry supports a number of built-in samplers to choose from. 
+OpenTelemetry supports a number of built-in samplers to choose from.
 The default sampler is `ParentOrElse(AlwaysOn)`.
 
 #### AlwaysOn

specification/trace/sdk_exporters/jaeger.md

@@ -19,7 +19,7 @@ and Jaeger.
 ### InstrumentationLibrary
 
 OpenTelemetry Span's `InstrumentationLibrary` MUST be reported as span `tags` to Jaeger using the following mapping.
- 
+
 | OpenTelemetry | Jaeger |
 | ------------- | ------ |
 | `InstrumentationLibrary.name`|`otel.instrumentation_library.name`|

specification/trace/sdk_exporters/zipkin.md

@@ -82,7 +82,7 @@ Zipkin.
 ### InstrumentationLibrary
 
 OpenTelemetry Span's `InstrumentationLibrary` MUST be reported as `tags` to Zipkin using the following mapping.
- 
+
 | OpenTelemetry | Zipkin
 | ------------- | ------ |
 | `InstrumentationLibrary.name`|`otel.instrumentation_library.name`|

specification/trace/semantic_conventions/http.md

@@ -86,7 +86,6 @@ Note that the items marked with [1] are different from the mapping defined in th
 | `http.response_content_length` | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length][] header. For requests using transport encoding, this should be the compressed size. | No |
 | `http.response_content_length_uncompressed` | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | No |
 
-
 It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed.
 
 [network attributes]: span-general.md#general-network-connection-attributes