diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 274c7d492e..bd97d7ebe9 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -13,6 +13,12 @@ jobs: steps: - uses: actions/checkout@v2 + - name: Lint markdown files + uses: avto-dev/markdown-lint@v1 + with: + ignore: "./**/CHANGELOG.md" + args: "./**/*.md" + - name: restore lerna uses: actions/cache@master # must use unreleased master to cache multiple paths id: cache diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000000..b5a4fe3721 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,7 @@ +{ + "MD013": false, + "MD024": false, + "MD033": false, + "MD041": false + } + \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfd36d4f4e..a55d04db14 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,9 +25,11 @@ The Conventional Commits specification is a lightweight convention on top of com We use [commitlint](https://github.com/conventional-changelog/commitlint) and [husky](https://github.com/typicode/husky) to prevent bad commit message. For example, you want to submit the following commit message `git commit -s -am "my bad commit"`. You will receive the following error : -``` + +```text ✖ type must be one of [ci, feat, fix, docs, style, refactor, perf, test, revert, chore] [type-enum] ``` + Here an exemple that will pass the verification: `git commit -s -am "chore(opentelemetry-core): update deps"` ### Fork @@ -35,7 +37,8 @@ Here an exemple that will pass the verification: `git commit -s -am "chore(opent In the interest of keeping this repository clean and manageable, you should work from a fork. To create a fork, click the 'Fork' button at the top of the repository, then clone the fork locally using `git clone git@github.com:USERNAME/opentelemetry-js-contrib.git`. You should also add this repository as an "upstream" repo to your local copy, in order to keep it up to date. You can add this as a remote like so: -``` + +```bash git remote add upstream https://github.com/open-telemetry/opentelemetry-js-contrib.git #verify that the upstream exists @@ -43,7 +46,8 @@ git remote -v ``` To update your fork, fetch the upstream repo's branches and commits, then merge your main with upstream's main: -``` + +```bash git fetch upstream git checkout main git merge upstream/main @@ -63,22 +67,26 @@ The `opentelemetry-js-contrib` project is written in TypeScript. - `npm test` tests code the same way that our CI will test it. - `npm run lint:fix` lint (and maybe fix) any changes. - ### Generating API documentation + - `npm run docs` to generate API documentation. Generates the documentation in `packages/opentelemetry-api/docs/out` ### Generating CHANGELOG documentation + - `npm run changelog` to generate CHANGELOG documentation in your terminal (see [RELEASING.md](RELEASING.md) for more details). ### Benchmarks + When two or more approaches must be compared, please write a benchmark in the benchmark/index.js module so that we can keep track of the most efficient algorithm. - `npm run bench` to run your benchmark. ## Contributing Vendor Components + This repo is generally meant for hosting components that work with popular open-source frameworks and tools. However, it is also possible to contribute components specific to a 3rd party vendor in this repo. ### Adding a New Vendor Component + Vendor components that are hosted in this repo will be versioned the same as all other contrib components, and released in lockstep with them under the `@opentelemetry` org in NPM. In exchange, vendor component contributors are expected to: @@ -96,4 +104,5 @@ In exchange, vendor component contributors are expected to: - Update their components' usage of Core APIs upon the introduction of breaking changes upstream ### Removing Vendor Components + All vendor components are subject to removal from the repo at the sole discretion of the maintainers. Reasons for removal include but are not limited to failing to adhere to any of the expectations defined above in a timely manner. "Timely manner" can vary depending on the urgency of the task, for example if a flaky unit test is blocking a release for the entire repo that would be far more urgent than responding to a question about usage. As a rule of thumb, 2-3 business days is a good goal for non-urgent response times. diff --git a/README.md b/README.md index 3d0cde26ee..1cc54df5e4 100644 --- a/README.md +++ b/README.md @@ -114,11 +114,13 @@ Node.JS `v8` | See [Node Support](#node-support) below Web Browsers | ✅ See [Browser Support](#browser-support) below ### Node Support + Automated tests are run using the latest release of each currently active version of Node.JS. While Node.JS v8 is no longer supported by the Node.JS team, the latest version of Node.JS v8 is still included in our testing suite. Please note that versions of Node.JS v8 prior to `v8.5.0` will NOT work, because OpenTelemetry Node depends on the `perf_hooks` module introduced in `v8.5.0` ### Browser Support + Automated browser tests are run in the latest version of Headless Chrome. There is currently no list of officially supported browsers, but OpenTelemetry is developed using standard web technologies with wide support and should work in currently supported versions of major browsers. diff --git a/RELEASING.md b/RELEASING.md index c0e908b88c..2a5b9b046e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -3,7 +3,7 @@ This repository uses [Release Please](https://github.com/googleapis/release-please) to manage its releases automatically and independently. Modified packages are automatically published to NPM when the auto-generated Release Please PR is merged. -# Manual Publishing Process +## Manual Publishing Process For posterity, or in the event of any failures with release-please, the process for performing a manual release is below. @@ -42,13 +42,16 @@ Decide on the next `major.minor.patch` release number based on [semver](http://s Since we use `lerna`, we can use [lerna-changelog](https://github.com/lerna/lerna-changelog#lerna-changelog) #### How to use + Pass your [github token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) to generate the changelog automatically. For security reasons, when you create a Github token, select the permissions: under **repo**, select **Access public repositories**, **commit status**. In your terminal, execute the following command: + ```bash GITHUB_AUTH= lerna-changelog ``` + It will print something like: ```md @@ -64,10 +67,12 @@ It will print something like: - Helpful Hacker ([@helpful-hacker](https://github.com/helpful-hacker)) - [@careful-coder](https://github.com/careful-coder) ``` + By default lerna-changelog will show all pull requests that have been merged since the latest tagged commit in the repository. That is however only true for pull requests **with certain labels applied** (see [lerna.json](lerna.json) for authorized labels). You can also use the `--from` and `--to` options to view a different range of pull requests: -``` + +```text GITHUB_AUTH=xxxxx lerna-changelog --from=v1.0.0 --to=v2.0.0 ``` @@ -102,6 +107,7 @@ done Check your e-mail and make sure the number of “you’ve published this module” emails matches the number you expect. ## Publish the GitHub Release + Publish the GitHub release, ensuring that the tag points to the newly landed commit corresponding to release proposal `x.y.z`. ## Update CHANGELOG @@ -110,7 +116,6 @@ Publish the GitHub release, ensuring that the tag points to the newly landed com * Create a new commit with the exact title: `Post Release: update CHANGELOG.md`. * Go through PR review and merge it to GitHub main branch. - ## Known Issues * The `examples/` and `getting-started/` folders are not part of lerna packages, we need to manually bump the version in `package.json`. diff --git a/examples/connect/README.md b/examples/connect/README.md index 290dc0e16c..6f757ab3a4 100644 --- a/examples/connect/README.md +++ b/examples/connect/README.md @@ -3,6 +3,7 @@ OpenTelemetry Connect Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (Collector Exporter), to give observability to distributed systems. This is a simple example that demonstrates tracing calls made to Connect API. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Span Events @@ -11,15 +12,15 @@ This is a simple example that demonstrates tracing calls made to Connect API. Th ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` ## Run the Application ### Collector - docker container - - Run docker container with collector +- Run docker container with collector ```sh # from this directory @@ -28,14 +29,14 @@ $ npm install ### Server - - Run the server +- Run the server ```sh # from this directory $ npm run server ``` - - Run the client +- Run the client ```sh # from this directory @@ -43,11 +44,13 @@ $ npm install ``` #### Zipkin UI -Go to Zipkin with your browser [http://localhost:9411/]() + +Go to Zipkin with your browser

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/dns/README.md b/examples/dns/README.md index 42e45f04d0..4020b97fd7 100644 --- a/examples/dns/README.md +++ b/examples/dns/README.md @@ -12,8 +12,8 @@ shows key aspects of tracing such as ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -27,14 +27,14 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ - Run the client ```sh -$ # from this directory -$ npm run zipkin:client +# from this directory +npm run zipkin:client ``` #### Zipkin UI `zipkin:client` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

@@ -43,14 +43,14 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace- - Run the client ```sh - $ # from this directory - $ npm run jaeger:client + # from this directory + npm run jaeger:client ``` #### Jaeger UI `jaeger:client` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

diff --git a/examples/express/README.md b/examples/express/README.md index 10fdc78c6c..ac1db4669e 100644 --- a/examples/express/README.md +++ b/examples/express/README.md @@ -4,6 +4,7 @@ OpenTelemetry Express Instrumentation allows the user to automatically collect t This is a simple example that demonstrates tracing calls made to Express API. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Span Events @@ -12,8 +13,8 @@ shows key aspects of tracing such as ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -24,14 +25,14 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Run the server +- Run the server ```sh # from this directory $ npm run zipkin:server ``` - - Run the client +- Run the client ```sh # from this directory @@ -39,21 +40,22 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ``` #### Zipkin UI + `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Run the server +- Run the server ```sh # from this directory $ npm run jaeger:server ``` - - Run the client +- Run the client ```sh # from this directory @@ -63,11 +65,12 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace- #### Jaeger UI `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/fastify/README.md b/examples/fastify/README.md index bde7fff0bc..6806f746bc 100644 --- a/examples/fastify/README.md +++ b/examples/fastify/README.md @@ -3,6 +3,7 @@ OpenTelemetry Fastify Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (Collector Exporter), to give observability to distributed systems. This is a simple example that demonstrates tracing calls made to Fastify API. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Span Events @@ -11,15 +12,15 @@ This is a simple example that demonstrates tracing calls made to Fastify API. Th ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` ## Run the Application ### Collector - docker container - - Run docker container with collector +- Run docker container with collector ```sh # from this directory @@ -28,14 +29,14 @@ $ npm install ### Server - - Run the server +- Run the server ```sh # from this directory $ npm run server ``` - - Run the client +- Run the client ```sh # from this directory @@ -43,11 +44,13 @@ $ npm install ``` #### Zipkin UI -Go to Zipkin with your browser [http://localhost:9411/]() + +Go to Zipkin with your browser

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/graphql/README.md b/examples/graphql/README.md index b4a9ba2826..e6dffdc35d 100644 --- a/examples/graphql/README.md +++ b/examples/graphql/README.md @@ -47,6 +47,7 @@ npm install 5. You can also write your own queries, open page `http://localhost:4000/graphql` 6. You can also test a `graphql-transform-federation` + ```shell script # from this directory npm run server:federation diff --git a/examples/grpc-census-prop/README.md b/examples/grpc-census-prop/README.md index c61ca42503..5627251c58 100644 --- a/examples/grpc-census-prop/README.md +++ b/examples/grpc-census-prop/README.md @@ -36,8 +36,8 @@ output the contents of `grpc.Metadata` which allows us to see the values of ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` ## Running the Client and Server combinations @@ -50,15 +50,15 @@ Propagation through `traceparent` header. - Run the server ```sh - $ # from this directory - $ npm run server:otel:defprop + # from this directory + npm run server:otel:defprop ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client:otel:defprop + # from this directory + npm run client:otel:defprop ``` ### Combination 2 @@ -69,15 +69,15 @@ on client. Propagation through `grpc-trace-bin` header. - Run the server ```sh - $ # from this directory - $ npm run server:otel:binprop + # from this directory + npm run server:otel:binprop ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client:census + # from this directory + npm run client:census ``` See [combination2](./combination2.md) for example output @@ -89,15 +89,15 @@ OpenCensus used on both client and server. Propagation through `grpc-trace-bin` - Run the server ```sh - $ # from this directory - $ npm run server:census + # from this directory + npm run server:census ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client:census + # from this directory + npm run client:census ``` ### Combination 4 @@ -108,20 +108,21 @@ client. Propagation through `grpc-trace-bin` header. - Run the server ```sh - $ # from this directory - $ npm run server:census + # from this directory + npm run server:census ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client:otel:binprop + # from this directory + npm run client:otel:binprop ``` See [combination4](./combination4.md) for example output ## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/grpc-census-prop/combination2.md b/examples/grpc-census-prop/combination2.md index fb6f0a799c..cd8b11d7a1 100644 --- a/examples/grpc-census-prop/combination2.md +++ b/examples/grpc-census-prop/combination2.md @@ -7,7 +7,7 @@ on client. Propagation through `grpc-trace-bin` header. Note: traceId **1565fbb4d6f042d8880bedb509bf6f2e** -``` +```sh $ npm run client:census > grpc-census-prop-example@0.9.0 client:census /opentelemetry-js-contrib/examples/grpc-census-prop @@ -18,8 +18,8 @@ Sleeping 5 seconds before shutdown to ensure all records are flushed. (node:14866) DeprecationWarning: grpc.load: Use the @grpc/proto-loader module with grpc.loadPackageDefinition instead < OPENTELEMETRY RootSpan: {traceId: 1565fbb4d6f042d8880bedb509bf6f2e, spanId: a5ccb3c920a18ace, name: tutorialsClient.capitalize } - ChildSpans: - {spanId: c92c3b3f955cdce1, name: grpc.rpc.Fetch/Capitalize} + ChildSpans: + {spanId: c92c3b3f955cdce1, name: grpc.rpc.Fetch/Capitalize} Completed. ``` @@ -27,7 +27,7 @@ Completed. Note: traceId **1565fbb4d6f042d8880bedb509bf6f2e** -``` +```sh $ npm run server:otel:binprop > grpc-census-prop-example@0.9.0 server:otel:binprop /opentelemetry-js-contrib/examples/grpc-census-prop diff --git a/examples/grpc-census-prop/combination4.md b/examples/grpc-census-prop/combination4.md index c105f57398..7f622dc7bb 100644 --- a/examples/grpc-census-prop/combination4.md +++ b/examples/grpc-census-prop/combination4.md @@ -7,7 +7,7 @@ client. Propagation through `grpc-trace-bin` header. Note: traceId **901c68f681e5a85a125b3dad82e51498** -``` +```sh $ npm run client:otel:binprop > grpc-census-prop-example@0.9.0 client:otel:binprop /opentelemetry-js-contrib/examples/grpc-census-prop @@ -50,7 +50,7 @@ Completed. Note: traceId **901c68f681e5a85a125b3dad82e51498** -``` +```sh $ npm run server:census > grpc-census-prop-example@0.9.0 server:census /opentelemetry-js-contrib/examples/grpc-census-prop @@ -93,6 +93,6 @@ Metadata { flags: 0 } traceid: 901c68f681e5a85a125b3dad82e51498 RootSpan: {traceId: 901c68f681e5a85a125b3dad82e51498, spanId: 63028b5ce96caec6, name: grpc.rpc.Fetch/Capitalize } - ChildSpans: - {spanId: d70a03f18955e762, name: tutorials.FetchImpl.capitalize} + ChildSpans: + {spanId: d70a03f18955e762, name: tutorials.FetchImpl.capitalize} ``` diff --git a/examples/grpc_dynamic_codegen/README.md b/examples/grpc_dynamic_codegen/README.md index f7f1f38310..1ece34d825 100644 --- a/examples/grpc_dynamic_codegen/README.md +++ b/examples/grpc_dynamic_codegen/README.md @@ -9,8 +9,8 @@ Using OpenTelemetry gRPC Instrumentation, we can collect traces of our system an ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -21,37 +21,38 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run zipkin:server + # from this directory + npm run zipkin:server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run zipkin:client + # from this directory + npm run zipkin:client ``` ### Jaeger - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run jaeger:server + # from this directory + npm run jaeger:server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run jaeger:client + # from this directory + npm run jaeger:client ``` ## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/hapi/README.md b/examples/hapi/README.md index 13ed19543b..7646b76fb6 100644 --- a/examples/hapi/README.md +++ b/examples/hapi/README.md @@ -3,6 +3,7 @@ OpenTelemetry Hapi Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (we can use Zipkin or Jaeger for this example), to give observability to distributed systems. This is a simple example that demonstrates tracing calls made in a Hapi application. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Span Attributes @@ -12,8 +13,8 @@ This is a simple example that demonstrates tracing calls made in a Hapi applicat ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -24,14 +25,14 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Run the server +- Run the server ```sh # from this directory $ npm run zipkin:server ``` - - Run the client +- Run the client ```sh # from this directory @@ -39,21 +40,22 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ``` #### Zipkin UI + `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Run the server +- Run the server ```sh # from this directory $ npm run jaeger:server ``` - - Run the client +- Run the client ```sh # from this directory @@ -63,11 +65,12 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace- #### Jaeger UI `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/koa/README.md b/examples/koa/README.md index d742289a03..936ae9111f 100644 --- a/examples/koa/README.md +++ b/examples/koa/README.md @@ -4,6 +4,7 @@ OpenTelemetry Koa Instrumentation allows the user to automatically collect trace This is a simple example that demonstrates tracing calls made in a Koa application. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Span Events @@ -12,8 +13,8 @@ shows key aspects of tracing such as ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -24,14 +25,14 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Run the server +- Run the server ```sh # from this directory $ npm run zipkin:server ``` - - Run the client +- Run the client ```sh # from this directory @@ -39,21 +40,22 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ``` #### Zipkin UI + `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Run the server +- Run the server ```sh # from this directory $ npm run jaeger:server ``` - - Run the client +- Run the client ```sh # from this directory @@ -63,11 +65,12 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace- #### Jaeger UI `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/mongodb/README.md b/examples/mongodb/README.md index cef079c078..fc2bec9b5d 100644 --- a/examples/mongodb/README.md +++ b/examples/mongodb/README.md @@ -3,16 +3,16 @@ OpenTelemetry Mongodb Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (we can use Zipkin or Jaeger for this example), to give observability to distributed systems. This is a modification of the Mongo example that executes multiple parallel requests that interact with a Mongodb server backend using the `mongo` npm module. The example displays traces using multiple connection methods. + - Create Collection Query - Insert Document Query - Fetch All Documents Query - ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -23,49 +23,52 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run server + # from this directory + npm run server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client + # from this directory + npm run client ``` #### Zipkin UI + `server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run server + # from this directory + npm run server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client + # from this directory + npm run client ``` + #### Jaeger UI `server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/mysql/README.md b/examples/mysql/README.md index ad91495968..26347036fe 100644 --- a/examples/mysql/README.md +++ b/examples/mysql/README.md @@ -3,16 +3,16 @@ OpenTelemetry MySQL Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (we can use Zipkin or Jaeger for this example), to give observability to distributed systems. This is a modification of the HTTP example that executes multiple parallel requests that interact with a MySQL server backend using the `mysql` npm module. The example displays traces using multiple connection methods. + - Direct Connection Query - Pool Connection Query - Cluster Pool Connection Query - ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -23,49 +23,52 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run server + # from this directory + npm run server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client + # from this directory + npm run client ``` #### Zipkin UI + `server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run server + # from this directory + npm run server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run client + # from this directory + npm run client ``` + #### Jaeger UI `server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/postgres/README.md b/examples/postgres/README.md index 548938e0bb..1385670cbd 100644 --- a/examples/postgres/README.md +++ b/examples/postgres/README.md @@ -4,6 +4,7 @@ OpenTelemetry PostgreSQL Instrumentation allows the user to automatically collec This is a simple example that demonstrates tracing HTTP request from client to server. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Child Span from a Remote Parent (on Server) @@ -14,8 +15,8 @@ shows key aspects of tracing such as ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -26,28 +27,28 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Start postgres via docker +- Start postgres via docker ```sh # from this directory npm run docker:start ``` - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run zipkin:server + # from this directory + npm run zipkin:server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run zipkin:client + # from this directory + npm run zipkin:client ``` - - Cleanup docker +- Cleanup docker ```sh # from this directory @@ -55,48 +56,51 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ``` #### Zipkin UI + `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Start postgres via docker +- Start postgres via docker ```sh # from this directory npm run docker:start ``` - - Run the server +- Run the server ```sh - $ # from this directory - $ npm run jaeger:server + # from this directory + npm run jaeger:server ``` - - Run the client +- Run the client ```sh - $ # from this directory - $ npm run jaeger:client + # from this directory + npm run jaeger:client ``` - - Cleanup docker +- Cleanup docker ```sh # from this directory npm run docker:stop ``` + #### Jaeger UI `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/examples/react-load/preact/README.md b/examples/react-load/preact/README.md index 2e7f523954..df29ae11e8 100644 --- a/examples/react-load/preact/README.md +++ b/examples/react-load/preact/README.md @@ -1,25 +1,29 @@ -# Overview +## Overview -The React Load plugin provides auto-instrumentation for react lifecycle methods. +The React Load plugin provides auto-instrumentation for react lifecycle methods. This example uses the plugin and exports them to the console. The example will show traces belong to the mounting, updating, and umounting flows as defined by React 16.4+. In this example we can show how this plugin can also be used in a Preact app. -# Installation -``` +## Installation + +```sh # from this directory npm install ``` -# Run the example +## Run the example + Run docker -``` + +```sh # from this directory npm run docker:start ``` Run app -``` + +```sh # from this directory npm run build npm start @@ -27,22 +31,27 @@ npm start By default, the application runs on port 8080. -Open Zipkin page at http://localhost:9411/zipkin/ - you should be able to see the spans in zipkin +Open Zipkin page at - you should be able to see the spans in zipkin + +### Screenshots of traces -## Screenshots of traces Take note of the parent-child relationships. -### First load -Upon loading, http://localhost:8080 mounting spans will be exported + +#### First load + +Upon loading, mounting spans will be exported

-### Pressing 'Enter' +#### Pressing 'Enter' + Here we can see the previous component unmounting and the new component mounting.

-### Pressing 'Make Request' +#### Pressing 'Make Request' + While in loading state:

@@ -51,15 +60,15 @@ After a few seconds (when the request is fulfilled):

+## Useful links -# Useful links - For more information on OpenTelemetry, visit: [opentelemetry.io][otel] - For more information on OpenTelemetry for Node.js, visit: [@opentelemetry/sdk-trace-node][otel-node] -# LICENSE +## LICENSE Apache 2.0 - See [LICENSE][license-url] for more information. [license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE [otel]: https://opentelemetry.io/ -[otel-node]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node \ No newline at end of file +[otel-node]: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node diff --git a/examples/react-load/react/README.md b/examples/react-load/react/README.md index b4ce87cc6f..7636647de2 100644 --- a/examples/react-load/react/README.md +++ b/examples/react-load/react/README.md @@ -1,26 +1,29 @@ # Overview -The React Load plugin provides auto-instrumentation for react lifecycle methods. +The React Load plugin provides auto-instrumentation for react lifecycle methods. This example uses the plugin and exports them to the console. The example will show traces belong to the mounting, updating, and umounting flows as defined by React 16.4+. -# Installation -``` +## Installation + +```sh # from this directory npm install ``` -# Run the example +## Run the example + Run docker -``` + +```sh # from this directory npm run docker:start ``` Run app -``` +```sh # from this directory npm run build npm start @@ -28,23 +31,27 @@ npm start By default, the application runs on port 5000. -Open Zipkin page at http://localhost:9411/zipkin/ - you should be able to see the spans in zipkin - +Open Zipkin page at - you should be able to see the spans in zipkin ## Screenshots of traces + Take note of the parent-child relationships. + ### First load -Upon loading, http://localhost:5000 mounting spans will be exported + +Upon loading, mounting spans will be exported

### Pressing 'Enter' + Here we can see the previous component unmounting and the new component mounting.

### Pressing 'Make Request' + While in loading state:

@@ -56,13 +63,12 @@ After a few seconds (when the request is fulfilled): Since the example adds in a delay to the request, we can see that reflected in the duration of some spans:

+## Useful links - -# Useful links - For more information on OpenTelemetry, visit: [opentelemetry.io][otel] - For more information on OpenTelemetry for Node.js, visit: [@opentelemetry/sdk-trace-node][otel-node] -# LICENSE +## LICENSE Apache 2.0 - See [LICENSE][license-url] for more information. diff --git a/examples/redis/README.md b/examples/redis/README.md index 073a9396cb..0ce3c4e8fa 100644 --- a/examples/redis/README.md +++ b/examples/redis/README.md @@ -4,6 +4,7 @@ OpenTelemetry Redis Instrumentation allows the user to automatically collect tra This is a simple example that demonstrates tracing calls to a Redis cache via an Express API. The example shows key aspects of tracing such as + - Root Span (on Client) - Child Span (on Client) - Child Span from a Remote Parent (on Server) @@ -14,8 +15,8 @@ shows key aspects of tracing such as ## Installation ```sh -$ # from this directory -$ npm install +# from this directory +npm install ``` Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html) @@ -26,28 +27,28 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ### Zipkin - - Start redis via docker +- Start redis via docker ```sh # from this directory npm run docker:start ``` - - Run the server +- Run the server ```sh # from this directory $ npm run zipkin:server ``` - - Run the client +- Run the client ```sh # from this directory npm run zipkin:client ``` - - Cleanup docker +- Cleanup docker ```sh # from this directory @@ -55,35 +56,36 @@ Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/ ``` #### Zipkin UI + `zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace-id)]() (e.g http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6) +Go to Zipkin with your browser (e.g )

### Jaeger - - Start redis via docker +- Start redis via docker ```sh # from this directory npm run docker:start ``` - - Run the server +- Run the server ```sh # from this directory $ npm run jaeger:server ``` - - Run the client +- Run the client ```sh # from this directory npm run jaeger:client ``` - - Cleanup docker +- Cleanup docker ```sh # from this directory @@ -93,11 +95,12 @@ Go to Zipkin with your browser [http://localhost:9411/zipkin/traces/(your-trace- #### Jaeger UI `jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`). -Go to Jaeger with your browser [http://localhost:16686/trace/(your-trace-id)]() (e.g http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6) +Go to Jaeger with your browser (e.g )

## Useful links + - For more information on OpenTelemetry, visit: - For more information on OpenTelemetry for Node.js, visit: diff --git a/metapackages/auto-instrumentations-node/README.md b/metapackages/auto-instrumentations-node/README.md index 232fcf06be..25d34d20d3 100644 --- a/metapackages/auto-instrumentations-node/README.md +++ b/metapackages/auto-instrumentations-node/README.md @@ -16,6 +16,7 @@ npm install --save @opentelemetry/auto-instrumentations-node ``` ## Usage + OpenTelemetry Meta Packages for Node automatically loads instrumentations for Node builtin modules and common packages. Custom configuration for each of the instrumentations can be passed to the function, by providing an object with the name of the instrumentation as a key, and its configuration as the value. @@ -52,6 +53,7 @@ registerInstrumentations({ }); ``` + ## Supported instrumentations - [@opentelemetry/instrumentation-dns](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-dns) diff --git a/packages/opentelemetry-browser-extension-autoinjection/README.md b/packages/opentelemetry-browser-extension-autoinjection/README.md index 737171c282..301dd77105 100644 --- a/packages/opentelemetry-browser-extension-autoinjection/README.md +++ b/packages/opentelemetry-browser-extension-autoinjection/README.md @@ -16,11 +16,12 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`. ### from Download -* Go to [Releases](https://github.com/svrnm/opentelemetry-browser-extension/releases) and download the latest opentelemetry-browser-extension--.zip from Assets. +* Go to [Releases](https://github.com/svrnm/opentelemetry-browser-extension/releases) and download the latest opentelemetry-browser-extension--.zip from Assets. * Unzip that file locally * Open a new browser window and go to chrome://extensions * Turn on "Developer Mode" -* Click on "Load unpacked" and the select the folder, where the unzipped extension lives. +* Click on "Load unpacked" and the select the folder, where the unzipped extension lives. + ### from Source Run the following in your shell to download and build the extension from source: @@ -32,7 +33,7 @@ npm install npm run build ``` -This will create a so-called unpacked extension into the `build/` folder you now can load into your browser: +This will create a so-called unpacked extension into the `build/` folder you now can load into your browser: * Open a new browser window and go to chrome://extensions * Turn on "Developer Mode" diff --git a/packages/opentelemetry-host-metrics/README.md b/packages/opentelemetry-host-metrics/README.md index 0562e4da76..4bb459c1ce 100644 --- a/packages/opentelemetry-host-metrics/README.md +++ b/packages/opentelemetry-host-metrics/README.md @@ -6,6 +6,7 @@ [![Apache License][license-image]][license-url] This module provides automatic collection of Host Metrics which includes metrics for: + * CPU * Memory * Network @@ -43,9 +44,9 @@ hostMetrics.start(); ## Useful links -- For more information on OpenTelemetry, visit: -- For more about OpenTelemetry JavaScript: -- For help or feedback on this project, join us in [GitHub Discussions][discussions-url] +* For more information on OpenTelemetry, visit: +* For more about OpenTelemetry JavaScript: +* For help or feedback on this project, join us in [GitHub Discussions][discussions-url] ## License diff --git a/packages/opentelemetry-id-generator-aws-xray/README.md b/packages/opentelemetry-id-generator-aws-xray/README.md index fc203d4feb..d4b29c2b30 100644 --- a/packages/opentelemetry-id-generator-aws-xray/README.md +++ b/packages/opentelemetry-id-generator-aws-xray/README.md @@ -14,13 +14,13 @@ enabling compatibility with AWS X-Ray. Compatible with OpenTelemetry JS API and SDK `1.0+`. -### Installation +## Installation ` npm install --save @opentelemetry/id-generator-aws-xray ` -### Usage +## Usage In the [global tracer configuration file](https://github.com/open-telemetry/opentelemetry-js/blob/master/getting-started/README.md#initialize-a-global-tracer), configure the following: @@ -36,7 +36,7 @@ const tracerConfig = { const tracerProvider = new NodeTracerProvider(tracerConfig); ``` -### Trace ID Details +## Trace ID Details Example trace ID format: 58406520a006649127e371903a2de979 @@ -51,15 +51,15 @@ A trace ID consists of two parts: - For more about OpenTelemetry JavaScript: - For help or feedback on this project, join us in [GitHub Discussions][discussions-url] -### License +## License Apache 2.0 - See [LICENSE][license-url] for more information. -[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions -[license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE -[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat -[dependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-contrib.svg?path=packages%2Fopentelemetry-id-generator-aws-xray -[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=packages%2Fopentelemetry-id-generator-aws-xray -[devDependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-contrib.svg?path=packages%2Fopentelemetry-id-generator-aws-xray&type=dev -[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=packages%2Fopentelemetry-id-generator-aws-xray&type=dev -[npm-url]: https://www.npmjs.com/package/@opentelemetry/id-generator-aws-xray -[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fid-generator-aws-xray.svg +[discussions-url]: +[license-url]: +[license-image]: +[dependencies-image]: +[dependencies-url]: +[devDependencies-image]: +[devDependencies-url]: +[npm-url]: +[npm-img]: diff --git a/packages/opentelemetry-propagation-utils/README.md b/packages/opentelemetry-propagation-utils/README.md index 9ca9cd6ac5..d4fb2c02bc 100644 --- a/packages/opentelemetry-propagation-utils/README.md +++ b/packages/opentelemetry-propagation-utils/README.md @@ -1,4 +1,5 @@ # OpenTelemetry Propagation Utils + [![NPM Published Version][npm-img]][npm-url] [![dependencies][dependencies-image]][dependencies-url] [![devDependencies][devDependencies-image]][devDependencies-url] @@ -7,6 +8,7 @@ A collection of propagation utils for opentelemetry. ## Install + ```sh npm install --save @opentelemetry/propagation-utils ``` @@ -56,4 +58,4 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [devDependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-contrib.svg?path=packages%2Fopentelemetry-propagation-utils&type=dev [devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-contrib?path=packages%2Fopentelemetry-propagation-utils&type=dev [npm-url]: https://www.npmjs.com/package/@opentelemetry/propagation-utils -[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fpropagation-utils.svg \ No newline at end of file +[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fpropagation-utils.svg diff --git a/packages/opentelemetry-test-utils/README.md b/packages/opentelemetry-test-utils/README.md index 7b31ed3c33..c4eb997d24 100644 --- a/packages/opentelemetry-test-utils/README.md +++ b/packages/opentelemetry-test-utils/README.md @@ -6,11 +6,13 @@ No guarantees are given to uses outside of [open-telemetry/opentelemetry-js-cont Compatible with OpenTelemetry JS API and SDK `1.0+`. ## Instrumentation Testing + This package exports a mocha [root hook plugin](https://mochajs.org/#root-hook-plugins), which implements common boilerplate code a developer probably needs for writing instrumentation unit tests in node. This package: + - Initializes and registers a global trace provider for tests. -- Registers a global memory exporter which can be referenced in test to access span. +- Registers a global memory exporter which can be referenced in test to access span. - Make sure there is only a single instance of an instrumentation class that is used across different `.spec.ts` files so patching is consistent, deterministic and idiomatic. - Reset the memory exporter before each test, so spans do not leak from one test to another. - Optionally - export the test traces to Jaeger for convenience while debugging and developing. @@ -18,17 +20,21 @@ This package: By using this package, testing instrumentation code can be shorter, and good practices for writing tests are more easily applied. ### Supporter Version -Since [root hook plugin](https://mochajs.org/#root-hook-plugins) are used, this package is compatible to mocha v8.0.0 and above. + +Since [root hook plugin](https://mochajs.org/#root-hook-plugins) are used, this package is compatible to mocha v8.0.0 and above. ### Usage -1. Add dev dependency on this package: -``` +1. Add dev dependency on this package: + +```sh npm install @opentelemetry/test-utils --save-dev ``` -2. [`require`](https://mochajs.org/#-require-module-r-module) this package in mocha invocation: + +1. [`require`](https://mochajs.org/#-require-module-r-module) this package in mocha invocation: As command line argument option to mocha: + ```js "scripts": { "test": "mocha --require @opentelemetry/test-utils", @@ -43,7 +49,7 @@ Or by using config file / package.json config: } ``` -3. In your `.spec` file, import `registerInstrumentationTesting` and `getTestSpans` functions and use them to create instrumentation class instance and make assertions in the test: +1. In your `.spec` file, import `registerInstrumentationTesting` and `getTestSpans` functions and use them to create instrumentation class instance and make assertions in the test: ```js import { getTestSpans, registerInstrumentationTesting } from '@opentelemetry/test-utils'; diff --git a/plugins/node/opentelemetry-instrumentation-aws-lambda/README.md b/plugins/node/opentelemetry-instrumentation-aws-lambda/README.md index 02f36b656d..57848698c5 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-lambda/README.md +++ b/plugins/node/opentelemetry-instrumentation-aws-lambda/README.md @@ -49,7 +49,7 @@ In your Lambda function configuration, add or update the `NODE_OPTIONS` environm | Options | Type | Description | | --- | --- | --- | | `requestHook` | `RequestHook` (function) | Hook for adding custom attributes before lambda starts handling the request. Receives params: `span, { event, context }` | -| `responseHook` | `ResponseHook` (function) | Hook for adding custom attributes before lambda returns the response. Receives params: `span, { err?, res? } ` | +| `responseHook` | `ResponseHook` (function) | Hook for adding custom attributes before lambda returns the response. Receives params: `span, { err?, res? }` | | `disableAwsContextPropagation` | `boolean` | By default, this instrumentation will try to read the context from the `_X_AMZN_TRACE_ID` environment variable set by Lambda, set this to `true` to disable this behavior | | `eventContextExtractor` | `EventContextExtractor` (function) | Function for providing custom context extractor in order to support different event types that are handled by AWS Lambda (e.g., SQS, CloudWatch, Kinesis, API Gateway). Applied only when `disableAwsContextPropagation` is set to `true`. Receives params: `event` | diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/doc/sns.md b/plugins/node/opentelemetry-instrumentation-aws-sdk/doc/sns.md index f42d5ec2ef..f18d64fcb7 100644 --- a/plugins/node/opentelemetry-instrumentation-aws-sdk/doc/sns.md +++ b/plugins/node/opentelemetry-instrumentation-aws-sdk/doc/sns.md @@ -12,10 +12,11 @@ The following methods are automatically enhanced: - OpenTelemetry trace context is injected as SNS MessageAttributes, so the service receiving the message can link cascading spans to the trace which created the message. ### Consumers -There are many potential consumers: SQS, Lambda, HTTP/S, Email, SMS, mobile notifications. each one of them will received the propagated context in its own way. +There are many potential consumers: SQS, Lambda, HTTP/S, Email, SMS, mobile notifications. each one of them will received the propagated context in its own way. ## Integration with SQS + AWS provide two ways of integrating SNS and SQS, one sends the message "as is" and one being parsed, this is called raw message delivery. When it is turn off (by default) message attributes (sent in SNS) will appear in the payload of SQS, if it turned on the payload will be parsed before sent to SQS and the SNS attributes will be mapped to SQS Message attribute which allow this instrumentation to have propagated context works out-of-the-box. @@ -24,4 +25,4 @@ If raw message delivery is turned off, you can solve it by enabling `sqsExtractC More details about raw message deliver can be found in [AWS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html) ->If you see partial / broken traces when integrating SNS with SQS this might be the reason \ No newline at end of file +>If you see partial / broken traces when integrating SNS with SQS this might be the reason diff --git a/plugins/node/opentelemetry-instrumentation-connect/README.md b/plugins/node/opentelemetry-instrumentation-connect/README.md index 16bea1cfe3..3c104c1625 100644 --- a/plugins/node/opentelemetry-instrumentation-connect/README.md +++ b/plugins/node/opentelemetry-instrumentation-connect/README.md @@ -50,7 +50,6 @@ registerInstrumentations({ See [examples/connect](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/examples/connect) for a short example. - ## Useful links - For more information on OpenTelemetry, visit: diff --git a/plugins/node/opentelemetry-instrumentation-fastify/README.md b/plugins/node/opentelemetry-instrumentation-fastify/README.md index fd9c9a96a1..5b005cb615 100644 --- a/plugins/node/opentelemetry-instrumentation-fastify/README.md +++ b/plugins/node/opentelemetry-instrumentation-fastify/README.md @@ -48,7 +48,6 @@ registerInstrumentations({ See [examples/fastify](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/examples/fastify) for a short example. - ## Useful links - For more information on OpenTelemetry, visit: diff --git a/plugins/node/opentelemetry-instrumentation-generic-pool/README.md b/plugins/node/opentelemetry-instrumentation-generic-pool/README.md index 89365fc51d..22f74b8199 100644 --- a/plugins/node/opentelemetry-instrumentation-generic-pool/README.md +++ b/plugins/node/opentelemetry-instrumentation-generic-pool/README.md @@ -17,9 +17,10 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`. ```bash npm install --save @opentelemetry/instrumentation-generic-pool ``` + ### Supported Versions - - - `>=2.0.0` + +- `>=2.0.0` ## Usage diff --git a/plugins/node/opentelemetry-instrumentation-graphql/README.md b/plugins/node/opentelemetry-instrumentation-graphql/README.md index 9f533c5a65..c7f98fbddb 100644 --- a/plugins/node/opentelemetry-instrumentation-graphql/README.md +++ b/plugins/node/opentelemetry-instrumentation-graphql/README.md @@ -54,6 +54,7 @@ registerInstrumentations({ | responseHook | GraphQLInstrumentationExecutionResponseHook | undefined | Hook that allows adding custom span attributes based on the data returned from "execute" GraphQL action. | | ## Examples + Can be found [here](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/examples/graphql) ## Useful links @@ -61,6 +62,7 @@ Can be found [here](https://github.com/open-telemetry/opentelemetry-js-contrib/t - For more information on OpenTelemetry, visit: - For more about OpenTelemetry JavaScript: - For help or feedback on this project, join us in [GitHub Discussions][discussions-url] + ## License Apache 2.0 - See [LICENSE][license-url] for more information. diff --git a/plugins/node/opentelemetry-instrumentation-knex/README.md b/plugins/node/opentelemetry-instrumentation-knex/README.md index e853485d1c..050f45aff1 100644 --- a/plugins/node/opentelemetry-instrumentation-knex/README.md +++ b/plugins/node/opentelemetry-instrumentation-knex/README.md @@ -20,7 +20,7 @@ npm install --save @opentelemetry/instrumentation-knex ### Supported Versions - - `>=0.10.0` +- `>=0.10.0` ## Usage diff --git a/plugins/node/opentelemetry-instrumentation-mongodb/README.md b/plugins/node/opentelemetry-instrumentation-mongodb/README.md index 10128bccb8..1bc9c57a69 100644 --- a/plugins/node/opentelemetry-instrumentation-mongodb/README.md +++ b/plugins/node/opentelemetry-instrumentation-mongodb/README.md @@ -19,7 +19,8 @@ npm install --save @opentelemetry/instrumentation-mongodb ``` ### Supported Versions - - `'>=3.3 <4` + +- `'>=3.3 <4` ## Usage diff --git a/plugins/node/opentelemetry-instrumentation-nestjs-core/README.md b/plugins/node/opentelemetry-instrumentation-nestjs-core/README.md index 096fed368a..03cf09fe5a 100644 --- a/plugins/node/opentelemetry-instrumentation-nestjs-core/README.md +++ b/plugins/node/opentelemetry-instrumentation-nestjs-core/README.md @@ -48,7 +48,7 @@ registerInstrumentations({ `.` | `request_context` | Traces the whole request context. | `http.*`, `nestjs.callback` `` | `handler` | Traces the work of a specific controller member function. | `nestjs.callback` -#### Attributes +### Attributes | Name | Description | ---- | ---- diff --git a/plugins/node/opentelemetry-instrumentation-router/README.md b/plugins/node/opentelemetry-instrumentation-router/README.md index 5e42f542f0..195422b1cd 100644 --- a/plugins/node/opentelemetry-instrumentation-router/README.md +++ b/plugins/node/opentelemetry-instrumentation-router/README.md @@ -17,8 +17,10 @@ Compatible with OpenTelemetry JS API and SDK `1.0+`. ```bash npm install --save @opentelemetry/instrumentation-router ``` + ### Supported Versions - - `>=1.0.0` + +- `>=1.0.0` ## Usage diff --git a/plugins/web/opentelemetry-plugin-react-load/README.md b/plugins/web/opentelemetry-plugin-react-load/README.md index 8f0cd85ace..45d2479055 100644 --- a/plugins/web/opentelemetry-plugin-react-load/README.md +++ b/plugins/web/opentelemetry-plugin-react-load/README.md @@ -27,6 +27,7 @@ BaseOpenTelemetryComponent.setTracer('name', 'version'); ``` To instrument components, extend `BaseOpenTelemetryComponent`: + ```js import { BaseOpenTelemetryComponent } from '@opentelemetry/plugin-react-load'; @@ -36,6 +37,7 @@ export class Component1 extends BaseOpenTelemetryComponent { ... } See [/examples/react-load](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/examples/react-load) for a short example. ## Useful links + - For more information on OpenTelemetry, visit: - For more about OpenTelemetry JavaScript: - For help or feedback on this project, join us in [GitHub Discussions][discussions-url] diff --git a/propagators/opentelemetry-propagator-aws-xray/README.md b/propagators/opentelemetry-propagator-aws-xray/README.md index 077644a185..a399246b09 100644 --- a/propagators/opentelemetry-propagator-aws-xray/README.md +++ b/propagators/opentelemetry-propagator-aws-xray/README.md @@ -13,13 +13,13 @@ This propagator translates the OpenTelemetry SpanContext into the equivalent AWS Compatible with OpenTelemetry JS API and SDK `1.0+`. -### Installation +## Installation -``` +```sh npm install --save @opentelemetry/propagator-aws-xray ``` -### Usage +## Usage In the [global tracer configuration file](https://github.com/open-telemetry/opentelemetry-js/blob/master/getting-started/README.md#initialize-a-global-tracer), configure the following: @@ -36,38 +36,38 @@ provider.register({ }); ``` -### Propagator Details +## Propagator Details Example header:`X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1` The header consists of three parts: the root trace ID, the parent ID and the sampling decision. -#### Root - The AWS X-Ray format trace ID +### Root - The AWS X-Ray format trace ID * Format: (spec-version)-(timestamp)-(UUID) - * spec_version - The version of the AWS X-Ray header format. Currently, only "1" is valid. - * timestamp - 32-bit number in base16 format, corresponds to the first 8 characters of the OpenTelemetry trace ID. Note, while X-Ray calls this timestamp, for the purpose of propagation it is opaque and any value will work. - * UUID - 96-bit random number in base16 format, corresponds to the last 10 characters of the OpenTelemetry trace ID. + * spec_version - The version of the AWS X-Ray header format. Currently, only "1" is valid. + * timestamp - 32-bit number in base16 format, corresponds to the first 8 characters of the OpenTelemetry trace ID. Note, while X-Ray calls this timestamp, for the purpose of propagation it is opaque and any value will work. + * UUID - 96-bit random number in base16 format, corresponds to the last 10 characters of the OpenTelemetry trace ID. Root is analogous to the [OpenTelemetry Trace ID](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext), with some small format changes. For additional reading, see the [AWS X-Ray Trace ID](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids) public documentation. -#### Parent - The ID of the AWS X-Ray Segment +### Parent - The ID of the AWS X-Ray Segment * 64-bit random number in base16 format. Populated from the [OpenTelemetry Span ID](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext). -#### Sampled - The sampling decision +### Sampled - The sampling decision * Defined in the AWS X-Ray specification as a tri-state field, with "0", "1" and "?" as valid values. Only "0" and "1" are used in this propagator. If "?", a new trace will be started. * Populated from the [OpenTelemetry trace flags](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext). ## Useful links -- For more information on OpenTelemetry, visit: -- For more about OpenTelemetry JavaScript: -- For help or feedback on this project, join us in [GitHub Discussions][discussions-url] +* For more information on OpenTelemetry, visit: +* For more about OpenTelemetry JavaScript: +* For help or feedback on this project, join us in [GitHub Discussions][discussions-url] -### License +## License Apache 2.0 - See [LICENSE][license-url] for more information.