open-telemetry
/
opentelemetry-js
mirror of https://github.com/open-telemetry/opentelemetry-js.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge api repository into main (#3245) 

Co-authored-by: Mayur Kale <mayurkale@google.com>
Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>
Co-authored-by: Naseem <naseemkullah@gmail.com>
Co-authored-by: Renovate Bot <bot@renovateapp.com>
Co-authored-by: Bartlomiej Obecny <bobecny@gmail.com>
Co-authored-by: Valentin Marchaud <contact@vmarchaud.fr>
Co-authored-by: Gerhard Stöbich <deb2001-github@yahoo.de>
Co-authored-by: shivkanya9146 <62445341+shivkanya9146@users.noreply.github.com>
Co-authored-by: legendecas <legendecas@gmail.com>
Co-authored-by: Mark Wolff <mark.wolff@microsoft.com>
Co-authored-by: Bryan Clement <bclement01@gmail.com>
Co-authored-by: dengliming <liming.d.pro@gmail.com>
Co-authored-by: srjames90 <srjames@lightstep.com>
Co-authored-by: Michael Goin <michaelgoin@users.noreply.github.com>
Co-authored-by: Mark <markseufert1@gmail.com>
Co-authored-by: Matthew Wear <matthew.wear@gmail.com>
Co-authored-by: Andrew <DrontXL@yandex.ru>
Co-authored-by: Srikanth Chekuri <srikanth.chekuri92@gmail.com>
Co-authored-by: Paul Draper <paulddraper@gmail.com>
Co-authored-by: Amir Blum <amirgiraffe@gmail.com>
Co-authored-by: Nev <54870357+MSNev@users.noreply.github.com>
Co-authored-by: Taavo-Taur "t2t2" Tammur <taavot@gmail.com>
Co-authored-by: Rauno Viskus <Rauno56@users.noreply.github.com>
Co-authored-by: Karen Xu <karenyrxu@gmail.com>
Co-authored-by: Adam Dobrawy <ad-m@users.noreply.github.com>
Co-authored-by: Trent Mick <trentm@gmail.com>
Co-authored-by: Severin Neumann <severin.neumann@altmuehlnet.de>
Co-authored-by: James <45812677+JamesJHPark@users.noreply.github.com>
Co-authored-by: Tyghe Vallard <vallardt@gmail.com>
Co-authored-by: Sam <samredmondtech@gmail.com>
Co-authored-by: Morgan Roderick <20321+mroderick@users.noreply.github.com>
Co-authored-by: Phillip Carter <pcarter@fastmail.com>
This commit is contained in:
Daniel Dyla 2022-09-12 14:10:48 -04:00 committed by GitHub
parent c1ef97de3e
commit 0f178d1e2e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
104 changed files with 7538 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
api/.commitlintrc.yml Normal file
View File

@ -0,0 +1,29 @@
extends:
- '@commitlint/config-conventional'
rules:
header-max-length: [1, 'always', 72]
type-enum:
- 2
- always
- - ci
- feat
- fix
- docs
- style
- refactor
- perf
- test
- revert
- chore
help: |
**Possible types**:
`ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle CI, BrowserStack, SauceLabs)
`feat`: Adds a new feature.
`fix`: Solves a bug.
`docs`: Adds or alters documentation. (example scopes: readme, worker, code_of_conduct, contributors)
`style`: Improves formatting, white-space.
`refactor`: Rewrites code without feature, performance or bug changes.
`perf`: Improves performance.
`test`: Adds or modifies tests. (example scopes: functionals, unit-tests)
`revert`: Changes that reverting other changes
`chore`: No production code change. Updating grunt tasks etc;

11
api/.editorconfig Normal file
View File

@ -0,0 +1,11 @@
# http://editorconfig.org
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

69
api/.eslintrc.js Normal file
View File

@ -0,0 +1,69 @@
module.exports = {
plugins: [
"@typescript-eslint",
"header",
"node"
],
extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
parser: "@typescript-eslint/parser",
parserOptions: {
"project": "./tsconfig.json"
},
rules: {
"quotes": [2, "single", { "avoidEscape": true }],
"@typescript-eslint/no-floating-promises": 2,
"@typescript-eslint/no-this-alias": "off",
"brace-style": ["error", "1tbs"],
"eqeqeq": [
"error",
"smart"
],
"prefer-rest-params": "off",
"@typescript-eslint/naming-convention": [
"error",
{
"selector": "memberLike",
"modifiers": ["private", "protected"],
"format": ["camelCase"],
"leadingUnderscore": "require"
}
],
"no-console": "error",
"no-shadow": "off",
"@typescript-eslint/no-shadow": ["warn"],
"@typescript-eslint/no-unused-vars": ["error", {"argsIgnorePattern": "^_", "args": "after-used"}],
"@typescript-eslint/no-inferrable-types": ["error", { ignoreProperties: true }],
"@typescript-eslint/no-empty-function": ["off"],
"@typescript-eslint/ban-types": ["warn", {
"types": {
"Function": null,
}
}],
"@typescript-eslint/no-shadow": ["warn"],
"arrow-parens": ["error", "as-needed"],
"node/no-deprecated-api": ["warn"],
"header/header": [2, "block", [{
pattern: / \* Copyright The OpenTelemetry Authors[\r\n]+ \*[\r\n]+ \* Licensed under the Apache License, Version 2\.0 \(the \"License\"\);[\r\n]+ \* you may not use this file except in compliance with the License\.[\r\n]+ \* You may obtain a copy of the License at[\r\n]+ \*[\r\n]+ \* https:\/\/www\.apache\.org\/licenses\/LICENSE-2\.0[\r\n]+ \*[\r\n]+ \* Unless required by applicable law or agreed to in writing, software[\r\n]+ \* distributed under the License is distributed on an \"AS IS\" BASIS,[\r\n]+ \* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\.[\r\n]+ \* See the License for the specific language governing permissions and[\r\n]+ \* limitations under the License\./gm,
template:
`\n * Copyright The OpenTelemetry Authors\n *\n * Licensed under the Apache License, Version 2.0 (the "License");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an "AS IS" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n `
}]]
},
overrides: [
{
"files": ["test/**/*.ts"],
"rules": {
"no-empty": "off",
"@typescript-eslint/ban-ts-ignore": "off",
"@typescript-eslint/no-empty-function": "off",
"@typescript-eslint/no-explicit-any": "off",
"@typescript-eslint/no-floating-promises": 1,
"@typescript-eslint/no-unused-vars": "off",
"@typescript-eslint/no-var-requires": "off",
"@typescript-eslint/no-shadow": ["off"],
"@typescript-eslint/no-floating-promises": ["off"],
"@typescript-eslint/no-non-null-assertion": ["off"],
"@typescript-eslint/explicit-module-boundary-types": ["off"]
}
}
]
};

39
api/.gitattributes vendored Normal file
View File

@ -0,0 +1,39 @@
## This .gitattributes file automatically formats the EOL character in certain filetypes within the repository
## Source code
# JavaScript, TypeScript, c, and h source files
*.js text eol=lf
*.ts text eol=lf
*.h text eol=lf diff=cpp
*.c text eol=lf diff=cpp
# Shell scripts
*.sh text eol=lf
*.bash text eol=lf
# Windows batch and PowerShell scripts
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf
##### Other file types #####
## Text files and documentation
*.txt text
README* text
RELEASING* text
CHANGELOG* text
CONTRIBUTING* text
INSTALL* text
LICENSE* text
## Non-text documentation
*.html text diff=html
*.pdf binary
*.json text eol=lf
*.rtf binary
## Git Properties
.gitignore text
.gitmodules text
.gitattributes text

15
api/.github/CODEOWNERS vendored Normal file
View File

@ -0,0 +1,15 @@
#####################################################
#
# List of approvers for OpenTelemetry JS SDK
#
#####################################################
#
# Learn about membership in OpenTelemetry community:
# https://github.com/open-telemetry/community/blob/master/community-membership.md
#
#
# Learn about CODEOWNERS file format:
# https://help.github.com/en/articles/about-code-owners
#
* @open-telemetry/javascript-approvers

34
api/.github/workflows/codeql-analysis.yml vendored Normal file
View File

@ -0,0 +1,34 @@
name: "CodeQL"
on:
workflow_dispatch:
schedule:
# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of the month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
# │ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
# │ │ │ │ │
# │ │ │ │ │
# │ │ │ │ │
# * * * * *
- cron: '30 1 * * *'
jobs:
CodeQL-Build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v2
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: javascript
- name: Autobuild
uses: github/codeql-action/autobuild@v1
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v1

27
api/.github/workflows/docs.yaml vendored Normal file
View File

@ -0,0 +1,27 @@
name: Deploy API Documentation
on:
release:
types: [published]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v2
- name: Install root dependencies
run: npm install --ignore-scripts
- name: Build 🔧
run: |
npm run compile
npm run docs
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages # The branch the action should deploy to.
FOLDER: docs/out # The folder the action should deploy.

37
api/.github/workflows/lint.yaml vendored Normal file
View File

@ -0,0 +1,37 @@
name: Lint
on:
push:
branches:
- main
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Lint markdown files
uses: docker://avtodev/markdown-lint:v1
with:
args: "./**/*.md -i ./CHANGELOG.md"
- name: Install dependencies
run: npm install
- name: Build 🔧
run: npm run compile
- name: Lint
run: npm run lint
- name: Check for Circular Dependencies
run: npm run cycle-check
- name: Generate Documentation 📜
run: npm run docs
- name: Test Docs
run: npm run docs:test

33
api/.github/workflows/release-please.yml vendored Normal file
View File

@ -0,0 +1,33 @@
on:
push:
branches:
- main
name: release-please
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: GoogleCloudPlatform/release-please-action@v2
id: release
with:
token: ${{secrets.RELEASE_PR_TOKEN}}
release-type: node
package-name: "@opentelemetry/api"
# The logic below handles the npm publication:
- uses: actions/checkout@v2
# these if statements ensure that a publication only occurs when
# a new release is created:
if: ${{ steps.release.outputs.release_created }}
- uses: actions/setup-node@v1
with:
node-version: 14
registry-url: 'https://registry.npmjs.org'
if: ${{ steps.release.outputs.release_created }}
- run: npm install
if: ${{ steps.release.outputs.release_created }}
- run: npm run compile
if: ${{ steps.release.outputs.release_created }}
- run: npm publish --tag next
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
if: ${{ steps.release.outputs.release_created }}

58
api/.github/workflows/test.yaml vendored Normal file
View File

@ -0,0 +1,58 @@
name: Unit Tests
on:
push:
branches:
- main
pull_request:
jobs:
unit-test:
strategy:
fail-fast: false
matrix:
node: ["8", "10", "12", "14", "16"]
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup Node
uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node }}
- name: Install Dependencies
run: npm install
- name: Compile 🔧
run: npm run compile
- name: Unit tests
run: npm run test
- name: Report Coverage
run: npm run codecov
if: ${{ matrix.node == '14' }}
browser-tests:
runs-on: ubuntu-latest
container:
image: circleci/node:12-browsers
steps:
- name: Permission Setup
run: sudo chmod -R 777 /github /__w
- name: Checkout
uses: actions/checkout@v2
- name: Install Dependencies
run: npm install
- name: Compile 🔧
run: npm run compile
- name: Unit tests
run: npm run test:browser
- name: Report Coverage
run: npm run codecov:browser

88
api/.gitignore vendored Normal file
View File

@ -0,0 +1,88 @@
# version.ts file is autogenerated at compile time
src/version.ts
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Bower dependency directory (https://bower.io/)
bower_components
# node-waf configuration
.lock-wscript
# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules/
jspm_packages/
build/
# TypeScript v1 declaration files
typings/
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# dotenv environment variables file
.env
# next.js build output
.next
# lock files
yarn.lock
package-lock.json
# generated gh-pages files
docs/out
.nyc_output
#lerna
.changelog
package.json.lerna_backup
# OS generated files
.DS_Store
# VsCode configs
.vscode/
#Visual Studio
.vs/
#IDEA
.idea
*.iml

7
api/.markdownlint.json Normal file
View File

@ -0,0 +1,7 @@
{
"MD013": false,
"MD024": false,
"MD033": false,
"MD041": false,
"MD026": false
}

4
api/.npmignore Normal file
View File

@ -0,0 +1,4 @@
/bin
/coverage
/doc
/test

207
api/CHANGELOG.md Normal file
View File

@ -0,0 +1,207 @@
# CHANGELOG
All notable changes to this project will be documented in this file.
## [1.2.0](https://www.github.com/open-telemetry/opentelemetry-js-api/compare/v1.1.0...v1.2.0) (2022-08-09)
### Features
* Add getActiveSpan to trace API ([#163](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/163)) ([17ccb3a](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/17ccb3a4e385bc5769ded6fc742c9782a93244a5))
* deprecate Sampler ([#166](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/166)) ([313b2e2](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/313b2e2225f246a6a9518ec4da6942f7d61babce))
## [1.1.0](https://www.github.com/open-telemetry/opentelemetry-js-api/compare/v1.0.4...v1.1.0) (2022-01-25)
### Features
* add tracestate implementation to api ([#147](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/147)) ([82842c7](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/82842c7097614e6ece99e73838ac5e94ff5460b7))
* define common attributes type ([#142](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/142)) ([ae9bead](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/ae9bead17750d35dec4b63cfae098087666abc85))
* **trace:** add optional schema url to TracerProvider.getTracer ([#129](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/129)) ([aa65fc6](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/aa65fc66809d45090d6e4951c265386d17ccc6f6))
### Bug Fixes
* export tracer options ([#154](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/154)) ([b125324](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/b125324438fb2f24eb80c7c6673afc8cfc99575e))
### [1.0.4](https://www.github.com/open-telemetry/opentelemetry-js-api/compare/v1.0.3...v1.0.4) (2021-12-18)
### Bug Fixes
* align globalThis fallbacks with otel-core ([#126](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/126)) ([3507de7](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/3507de7c3b95396696657c021953b0b24a63a029))
### [1.0.3](https://www.github.com/open-telemetry/opentelemetry-js-api/compare/v1.0.2...v1.0.3) (2021-08-30)
### Bug Fixes
* remove all circular dependencies ([#119](https://www.github.com/open-telemetry/opentelemetry-js-api/issues/119)) ([a8083e8](https://www.github.com/open-telemetry/opentelemetry-js-api/commit/a8083e84b23227828745da80fd5fe512357dd34b))
## 1.0.2
### :bug: Bug Fix
* [#105](https://github.com/open-telemetry/opentelemetry-js-api/pull/105) fix: set delegate after successful registration ([@Flarna](https://github.com/Flarna))
* [#94](https://github.com/open-telemetry/opentelemetry-js-api/pull/94) fix: enforce strict equality on prerelease versions ([@dyladan](https://github.com/dyladan))
### :memo: Documentation
* [#106](https://github.com/open-telemetry/opentelemetry-js-api/pull/106) docs: fix crash in README example ([@trentm](https://github.com/trentm))
* [#101](https://github.com/open-telemetry/opentelemetry-js-api/pull/101) docs: Format example for tracer.startActiveSpan ([@ad-m](https://github.com/ad-m))
* [#99](https://github.com/open-telemetry/opentelemetry-js-api/pull/99) chore: fix link to API docs ([@dyladan](https://github.com/dyladan))
### :house: Internal
* [#109](https://github.com/open-telemetry/opentelemetry-js-api/pull/109) internal: add missing approvers from core ([@dyladan](https://github.com/dyladan))
* [#103](https://github.com/open-telemetry/opentelemetry-js-api/pull/103) chore: reuse NoopTracer in ProxyTracer ([@Flarna](https://github.com/Flarna))
### Committers: 4
* Adam Dobrawy ([@ad-m](https://github.com/ad-m))
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
* Gerhard Stöbich ([@Flarna](https://github.com/Flarna))
* Trent Mick ([@trentm](https://github.com/trentm))
## 1.0.1
### :bug: Bug Fix
* [#96](https://github.com/open-telemetry/opentelemetry-js-api/pull/96) chore: remove circular dependency ([@dyladan](https://github.com/dyladan))
### Committers: 1
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
## 1.0.0
### :memo: Documentation
* [#89](https://github.com/open-telemetry/opentelemetry-js-api/pull/89) chore: update upgrade guidelines ([@dyladan](https://github.com/dyladan))
### :house: Internal
* [#90](https://github.com/open-telemetry/opentelemetry-js-api/pull/90) chore: enable typescript 4.3 noImplicitOverride option ([@Flarna](https://github.com/Flarna))
### Committers: 2
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
* Gerhard Stöbich ([@Flarna](https://github.com/Flarna))
## 0.21.0
### :boom: Breaking Change
* [#78](https://github.com/open-telemetry/opentelemetry-js-api/pull/78) feat: unify signatures of `with` and `bind` ([@Rauno56](https://github.com/Rauno56))
* [#46](https://github.com/open-telemetry/opentelemetry-js-api/pull/46) chore: do not export singletons ([@dyladan](https://github.com/dyladan))
### :rocket: Enhancement
* [#81](https://github.com/open-telemetry/opentelemetry-js-api/pull/81) chore: function overloads implementation of startActiveSpan in noop t… ([@naseemkullah](https://github.com/naseemkullah))
### :house: Internal
* [#84](https://github.com/open-telemetry/opentelemetry-js-api/pull/84) chore: remove unused backwards compatibility folder ([@Flarna](https://github.com/Flarna))
* [#85](https://github.com/open-telemetry/opentelemetry-js-api/pull/85) chore: add node:16 to the test matrix ([@Rauno56](https://github.com/Rauno56))
* [#63](https://github.com/open-telemetry/opentelemetry-js-api/pull/63) feat: debug log global registrations and logger overwrites ([@Rauno56](https://github.com/Rauno56))
* [#75](https://github.com/open-telemetry/opentelemetry-js-api/pull/75) Add CodeQL Security Scan ([@xukaren](https://github.com/xukaren))
* [#79](https://github.com/open-telemetry/opentelemetry-js-api/pull/79) chore: fix eslint config ([@Rauno56](https://github.com/Rauno56))
### Committers: 5
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
* Gerhard Stöbich ([@Flarna](https://github.com/Flarna))
* Karen Xu ([@xukaren](https://github.com/xukaren))
* Naseem ([@naseemkullah](https://github.com/naseemkullah))
* Rauno Viskus ([@Rauno56](https://github.com/Rauno56))
## 0.20.0
### :rocket: Enhancement
* [#69](https://github.com/open-telemetry/opentelemetry-js-api/pull/69) feat(context): add utils method to remove keys from context ([@vmarchaud](https://github.com/vmarchaud))
* [#71](https://github.com/open-telemetry/opentelemetry-js-api/pull/71) chore: export baggage ([@dyladan](https://github.com/dyladan))
### Committers: 2
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
* Valentin Marchaud ([@vmarchaud](https://github.com/vmarchaud))
## 0.19.0
### :boom: Breaking Change
* [#55](https://github.com/open-telemetry/opentelemetry-js-api/pull/55) chore: move baggage methods in propagation namespace ([@vmarchaud](https://github.com/vmarchaud))
* [#65](https://github.com/open-telemetry/opentelemetry-js-api/pull/65) chore: remove suppress instrumentation ([@dyladan](https://github.com/dyladan))
* [#60](https://github.com/open-telemetry/opentelemetry-js-api/pull/60) chore: removing timed event ([@obecny](https://github.com/obecny))
* [#58](https://github.com/open-telemetry/opentelemetry-js-api/pull/58) chore: use spancontext for link ([@dyladan](https://github.com/dyladan))
* [#47](https://github.com/open-telemetry/opentelemetry-js-api/pull/47) chore: move span method for context in trace API #40 ([@vmarchaud](https://github.com/vmarchaud))
* [#45](https://github.com/open-telemetry/opentelemetry-js-api/pull/45) chore: rename `span#context()` to `span#spanContext` ([@dyladan](https://github.com/dyladan))
* [#43](https://github.com/open-telemetry/opentelemetry-js-api/pull/43) chore: renaming noop span to non recording span ([@obecny](https://github.com/obecny))
* [#32](https://github.com/open-telemetry/opentelemetry-js-api/pull/32) feat!: return boolean success value from setGlobalXXX methods ([@dyladan](https://github.com/dyladan))
### :rocket: Enhancement
* [#62](https://github.com/open-telemetry/opentelemetry-js-api/pull/62) chore: adding component logger ([@obecny](https://github.com/obecny))
* [#54](https://github.com/open-telemetry/opentelemetry-js-api/pull/54) feat: add tracer.startActiveSpan() ([@naseemkullah](https://github.com/naseemkullah))
* [#58](https://github.com/open-telemetry/opentelemetry-js-api/pull/58) chore: use spancontext for link ([@dyladan](https://github.com/dyladan))
* [#51](https://github.com/open-telemetry/opentelemetry-js-api/pull/51) feat: add function to wrap SpanContext in NonRecordingSpan #49 ([@dyladan](https://github.com/dyladan))
### :memo: Documentation
* [#64](https://github.com/open-telemetry/opentelemetry-js-api/pull/64) chore: document the reason for symbol.for ([@dyladan](https://github.com/dyladan))
* [#44](https://github.com/open-telemetry/opentelemetry-js-api/pull/44) chore: updating readme headline and fixing links ([@obecny](https://github.com/obecny))
### Committers: 6
* Bartlomiej Obecny ([@obecny](https://github.com/obecny))
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
* Gerhard Stöbich ([@Flarna](https://github.com/Flarna))
* Naseem ([@naseemkullah](https://github.com/naseemkullah))
* Valentin Marchaud ([@vmarchaud](https://github.com/vmarchaud))
* t2t2 ([@t2t2](https://github.com/t2t2))
## 1.0.0-rc.0
### :memo: Documentation
* [#20](https://github.com/open-telemetry/opentelemetry-js-api/pull/20) docs: document latest manual tracing ([@dyladan](https://github.com/dyladan))
* [#18](https://github.com/open-telemetry/opentelemetry-js-api/pull/18) chore: deploy docs on a release ([@dyladan](https://github.com/dyladan))
* [#19](https://github.com/open-telemetry/opentelemetry-js-api/pull/19) docs: fix readme links ([@dyladan](https://github.com/dyladan))
### Committers: 1
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
## 0.18.1
### :bug: Bug Fix
* [#16](https://github.com/open-telemetry/opentelemetry-js-api/pull/16) fix: Reverse the direction of the semver check ([@dyladan](https://github.com/dyladan))
### Committers: 1
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
## v0.18.0
### :boom: Breaking Change
* [#9](https://github.com/open-telemetry/opentelemetry-js-api/pull/9) chore: refactor diag logger ([@dyladan](https://github.com/dyladan))
### :rocket: Enhancement
* [#10](https://github.com/open-telemetry/opentelemetry-js-api/pull/10) Use semver to determine API compatibility ([@dyladan](https://github.com/dyladan))
### :house: Internal
* [#12](https://github.com/open-telemetry/opentelemetry-js-api/pull/12) chore: don't disable rule eqeqeq ([@Flarna](https://github.com/Flarna))
* [#8](https://github.com/open-telemetry/opentelemetry-js-api/pull/8) chore: remove nycrc in favor of tsconfig reporting ([@dyladan](https://github.com/dyladan))
* [#3](https://github.com/open-telemetry/opentelemetry-js-api/pull/3) chore: add test workflow ([@dyladan](https://github.com/dyladan))
* [#4](https://github.com/open-telemetry/opentelemetry-js-api/pull/4) chore: remove package lock ([@dyladan](https://github.com/dyladan))
* [#2](https://github.com/open-telemetry/opentelemetry-js-api/pull/2) chore: add lint workflow ([@dyladan](https://github.com/dyladan))
### Committers: 2
* Daniel Dyla ([@dyladan](https://github.com/dyladan))
* Gerhard Stöbich ([@Flarna](https://github.com/Flarna))
## v0.17.0
Versions previous to `0.18.0` were developed in another repository.
To see previous changelog entries see the [CHANGELOG.md](https://github.com/open-telemetry/opentelemetry-js/blob/main/CHANGELOG.md).

201
api/LICENSE Normal file
View File

@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

140
api/README.md Normal file
View File

@ -0,0 +1,140 @@
---
<p align="center">
<strong>
<a href="https://open-telemetry.github.io/opentelemetry-js-api">API Documentation<a/>
&nbsp;&nbsp;&bull;&nbsp;&nbsp;
<a href="https://github.com/open-telemetry/opentelemetry-js/discussions">Getting In Touch (GitHub Discussions)<a/>
</strong>
</p>
<p align="center">
<a href="https://github.com/open-telemetry/opentelemetry-js-api/releases">
<img alt="GitHub release (latest by date including pre-releases)" src="https://img.shields.io/github/v/release/open-telemetry/opentelemetry-js-api?include_prereleases&style=for-the-badge">
</a>
<a href="https://codecov.io/gh/open-telemetry/opentelemetry-js-api/branch/main/">
<img alt="Codecov Status" src="https://img.shields.io/codecov/c/github/open-telemetry/opentelemetry-js-api?style=for-the-badge">
</a>
<a href="https://github.com/open-telemetry/opentelemetry-js-api/blob/main/LICENSE">
<img alt="license" src="https://img.shields.io/badge/license-Apache_2.0-green.svg?style=for-the-badge">
</a>
<br/>
<a href="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/docs.yaml">
<img alt="Build Status" src="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/test.yaml/badge.svg?branch=main">
</a>
<a href="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/test.yaml?query=branch%3Amain">
<img alt="Build Status" src="https://github.com/open-telemetry/opentelemetry-js-api/actions/workflows/docs.yaml/badge.svg">
</a>
</p>
---
# OpenTelemetry API for JavaScript
[![NPM Published Version][npm-img]][npm-url]
This package provides everything needed to interact with the OpenTelemetry API, including all TypeScript interfaces, enums, and no-op implementations. It is intended for use both on the server and in the browser.
The methods in this package perform no operations by default. This means they can be safely called by a library or end-user application whether there is an SDK registered or not. In order to generate and export telemetry data, you will also need an SDK such as the [OpenTelemetry JS SDK][opentelemetry-js].
## Tracing Quick Start
### You Will Need
- An application you wish to instrument
- [OpenTelemetry JS SDK][opentelemetry-js]
- Node.js >=8.5.0 (14+ is preferred) or an ECMAScript 5+ compatible browser
**Note:** ECMAScript 5+ compatibility is for this package only. Please refer to the documentation for the SDK you are using to determine its minimum ECMAScript version.
**Note for library authors:** Only your end users will need an OpenTelemetry SDK. If you wish to support OpenTelemetry in your library, you only need to use the OpenTelemetry API. For more information, please read the [tracing documentation][docs-tracing].
### Install Dependencies
```sh
npm install @opentelemetry/api @opentelemetry/sdk-trace-base
```
### Trace Your Application
In order to get started with tracing, you will need to first register an SDK. The SDK you are using may provide a convenience method which calls the registration methods for you, but if you would like to call them directly they are documented here: [sdk registration methods][docs-sdk-registration].
Once you have registered an SDK, you can start and end spans. A simple example of basic SDK registration and tracing a simple operation is below. The example should export spans to the console once per second. For more information, see the [tracing documentation][docs-tracing].
```javascript
const { trace } = require("@opentelemetry/api");
const { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
// Create and register an SDK
const provider = new BasicTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
trace.setGlobalTracerProvider(provider);
// Acquire a tracer from the global tracer provider which will be used to trace the application
const name = 'my-application-name';
const version = '0.1.0';
const tracer = trace.getTracer(name, version);
// Trace your application by creating spans
async function operation() {
const span = tracer.startSpan("do operation");
// mock some work by sleeping 1 second
await new Promise((resolve, reject) => {
setTimeout(resolve, 1000);
})
span.end();
}
async function main() {
while (true) {
await operation();
}
}
main();
```
## Version Compatibility
Because the npm installer and node module resolution algorithm could potentially allow two or more copies of any given package to exist within the same `node_modules` structure, the OpenTelemetry API takes advantage of a variable on the `global` object to store the global API. When an API method in the API package is called, it checks if this `global` API exists and proxies calls to it if and only if it is a compatible API version. This means if a package has a dependency on an OpenTelemetry API version which is not compatible with the API used by the end user, the package will receive a no-op implementation of the API.
## Upgrade Guidelines
### 0.21.0 to 1.0.0
No breaking changes
### 0.20.0 to 0.21.0
- [#78](https://github.com/open-telemetry/opentelemetry-js-api/issues/78) `api.context.bind` arguments reversed and `context` is now a required argument.
- [#46](https://github.com/open-telemetry/opentelemetry-js-api/issues/46) Noop classes and singletons are no longer exported. To create a noop span it is recommended to use `api.trace.wrapSpanContext` with `INVALID_SPAN_CONTEXT` instead of using the `NOOP_TRACER`.
### 1.0.0-rc.3 to 0.20.0
- Removing `TimedEvent` which was not part of spec
- `HttpBaggage` renamed to `HttpBaggagePropagator`
- [#45](https://github.com/open-telemetry/opentelemetry-js-api/pull/45) `Span#context` renamed to `Span#spanContext`
- [#47](https://github.com/open-telemetry/opentelemetry-js-api/pull/47) `getSpan`/`setSpan`/`getSpanContext`/`setSpanContext` moved to `trace` namespace
- [#55](https://github.com/open-telemetry/opentelemetry-js-api/pull/55) `getBaggage`/`setBaggage`/`createBaggage` moved to `propagation` namespace
## Useful links
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
- 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.
[opentelemetry-js]: https://github.com/open-telemetry/opentelemetry-js
[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/api
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fapi.svg
[docs-tracing]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/tracing.md
[docs-sdk-registration]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/sdk-registration.md

234
api/docs/context.md Normal file
View File

@ -0,0 +1,234 @@
# Context
In order for OpenTelemetry to work, it must store and propagate important telemetry data.
For example, when a request is received and a span is started it must be available to a component which creates its child span.
To solve this problem, OpenTelemetry stores the span in the Context.
This document describes the OpenTelemetry context API for JavaScript and how it is used.
_Context Specification: <https://github.com/open-telemetry/opentelemetry-specification/blob/v1.6.0/specification/context/context.md>_
_Context API Reference: <https://open-telemetry.github.io/opentelemetry-js-api/classes/contextapi.html>_
- [Context Manager](#context-manager)
- [Root Context](#root-context)
- [Context Keys](#context-keys)
- [Basic Operations](#basic-operations)
- [Get Entry](#get-entry)
- [Set Entry](#set-entry)
- [Delete Entry](#delete-entry)
- [Active Context](#active-context)
- [Get Active Context](#get-active-context)
- [Set Active Context](#set-active-context)
- [Example](#example)
## Context Manager
The context API depends on a context manager to work.
The examples in this document will assume you have already configured a context manager.
Typically the context manager is provided by your SDK, however it is possible to register one directly like this:
```typescript
import * as api from "@opentelemetry/api";
import { AsyncHooksContextManager } from "@opentelemetry/context-async-hooks";
const contextManager = new AsyncHooksContextManager();
contextManager.enable();
api.context.setGlobalContextManager(contextManager);
```
## Root Context
The `ROOT_CONTEXT` is the empty context.
If no context is active, the `ROOT_CONTEXT` is active.
Active context is explained below [Active Context](#active-context).
## Context Keys
Context entries are key-value pairs.
Keys can be created by calling `api.createContextKey(description)`.
```typescript
import * as api from "@opentelemetry/api";
const key1 = api.createContextKey("My first key");
const key2 = api.createContextKey("My second key");
```
## Basic Operations
### Get Entry
Entries are accessed using the `context.getValue(key)` method.
```typescript
import * as api from "@opentelemetry/api";
const key = api.createContextKey("some key");
// ROOT_CONTEXT is the empty context
const ctx = api.ROOT_CONTEXT;
const value = ctx.getValue(key);
```
### Set Entry
Entries are created by using the `context.setValue(key, value)` method.
Setting a context entry creates a new context with all the entries of the previous context, but with the new entry.
Setting a context entry does not modify the previous context.
```typescript
import * as api from "@opentelemetry/api";
const key = api.createContextKey("some key");
const ctx = api.ROOT_CONTEXT;
// add a new entry
const ctx2 = ctx.setValue(key, "context 2");
// ctx2 contains the new entry
console.log(ctx2.getValue(key)) // "context 2"
// ctx is unchanged
console.log(ctx.getValue(key)) // undefined
```
### Delete Entry
Entries are removed by calling `context.deleteValue(key)`.
Deleting a context entry creates a new context with all the entries of the previous context, but without the entry identified by the key.
Deleting a context entry does not modify the previous context.
```typescript
import * as api from "@opentelemetry/api";
const key = api.createContextKey("some key");
const ctx = api.ROOT_CONTEXT;
const ctx2 = ctx.setValue(key, "context 2");
// remove the entry
const ctx3 = ctx.deleteValue(key);
// ctx3 does not contain the entry
console.log(ctx3.getValue(key)) // undefined
// ctx2 is unchanged
console.log(ctx2.getValue(key)) // "context 2"
// ctx is unchanged
console.log(ctx.getValue(key)) // undefined
```
## Active Context
**IMPORTANT**: This assumes you have configured a Context Manager.
Without one, `api.context.active()` will _ALWAYS_ return the `ROOT_CONTEXT`.
The active context is the context which is returned by `api.context.active()`.
The context object contains entries which allow tracing components which are tracing a single thread of execution to communicate with each other and ensure the trace is successfully created.
For example, when a span is created it may be added to the context.
Later, when another span is created it may use the span from the context as its parent span.
This is accomplished through the use of mechanisms like [async_hooks](https://nodejs.org/api/async_hooks.html) or [AsyncLocalStorage](https://nodejs.org/api/async_context.html#async_context_class_asynclocalstorage) in node, or [zone.js](https://github.com/angular/zone.js/) on the web in order to propagate the context through a single execution.
If no context is active, the `ROOT_CONTEXT` is returned, which is just the empty context object.
### Get Active Context
The active context is the context which is returned by `api.context.active()`.
```typescript
import * as api from "@opentelemetry/api";
// Returns the active context
// If no context is active, the ROOT_CONTEXT is returned
const ctx = api.context.active();
```
### Set Active Context
A context can be made active by use of `api.context.with(ctx, callback)`.
During execution of the `callback`, the context passed to `with` will be returned by `context.active`.
```typescript
import * as api from "@opentelemetry/api";
const key = api.createContextKey("Key to store a value");
const ctx = api.context.active();
api.context.with(ctx.setValue(key, "context 2"), async () => {
// "context 2" is active
console.log(api.context.active().getValue(key)) // "context 2"
});
```
The return value of `api.context.with(context, callback)` is the return value of the callback.
The callback is always called synchronously.
```typescript
import * as api from "@opentelemetry/api";
const name = await api.context.with(api.context.active(), async () => {
const row = await db.getSomeValue();
return row["name"];
});
console.log(name); // name returned by the db
```
Active context executions may be nested.
```typescript
import * as api from "@opentelemetry/api";
const key = api.createContextKey("Key to store a value");
const ctx = api.context.active();
// No context is active
console.log(api.context.active().getValue(key)); // undefined
api.context.with(ctx.setValue(key, "context 2"), () => {
// "context 2" is active
console.log(api.context.active().getValue(key)) // "context 2"
api.context.with(ctx.setValue(key, "context 3"), () => {
// "context 3" is active
console.log(api.context.active().getValue(key)) // "context 3"
});
// "context 2" is active
console.log(api.context.active().getValue(key)) // "context 2"
});
// No context is active
console.log(api.context.active().getValue(key)); // undefined
```
### Example
This more complex example illustrates how the context is not modified, but new context objects are created.
```typescript
import * as api from "@opentelemetry/api";
const key = api.createContextKey("Key to store a value");
const ctx = api.context.active(); // Returns ROOT_CONTEXT when no context is active
const ctx2 = ctx.setValue(key, "context 2"); // does not modify ctx
console.log(ctx.getValue(key)) //? undefined
console.log(ctx2.getValue(key)) //? "context 2"
const ret = api.context.with(ctx2, () => {
const ctx3 = api.context.active().setValue(key, "context 3");
console.log(api.context.active().getValue(key)); //? "context 2"
console.log(ctx.getValue(key)) //? undefined
console.log(ctx2.getValue(key)) //? "context 2"
console.log(ctx3.getValue(key)) //? "context 3"
api.context.with(ctx3, () => {
console.log(api.context.active().getValue(key)); //? "context 3"
});
console.log(api.context.active().getValue(key)); //? "context 2"
return "return value"
});
// The value returned by the callback is returned to the caller
console.log(ret); //? "return value"
```

3
api/docs/library-author.md Normal file
View File

@ -0,0 +1,3 @@
# OpenTelemetry for Library Authors
TODO

5
api/docs/propagation.md Normal file
View File

@ -0,0 +1,5 @@
# Propagation
TODO
_Propagation API reference: <https://open-telemetry.github.io/opentelemetry-js-api/classes/propagationapi.html>_

28
api/docs/sdk-registration.md Normal file
View File

@ -0,0 +1,28 @@
# SDK Registration Methods
These methods are used to register a compatible OpenTelemetry SDK. Some SDKs like the [OpenTelemetry JS SDK][opentelemetry-js] provide convenience methods which call these registration methods for you.
- [Trace API Documentation][trace-api-docs]
- [Propagation API Documentation][propagation-api-docs]
- [Context API Documentation][context-api-docs]
```javascript
const api = require("@opentelemetry/api");
/* Register a global TracerProvider */
api.trace.setGlobalTracerProvider(tracerProvider);
/* returns tracerProvider (no-op if a working provider has not been initialized) */
api.trace.getTracerProvider();
/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized) */
api.trace.getTracer(name, version);
/* Register a global Propagator */
api.propagation.setGlobalPropagator(httpTraceContextPropagator);
/* Register a global Context Manager */
api.context.setGlobalContextManager(asyncHooksContextManager);
```
[trace-api-docs]: https://open-telemetry.github.io/opentelemetry-js-api/classes/traceapi.html
[propagation-api-docs]: https://open-telemetry.github.io/opentelemetry-js-api/classes/propagationapi.html
[context-api-docs]: https://open-telemetry.github.io/opentelemetry-js-api/classes/contextapi.html

214
api/docs/tracing.md Normal file
View File

@ -0,0 +1,214 @@
# Tracing
This quick start is for end users of OpenTelemetry who wish to manually trace their applications. If you are a library author, please see the [Library Authors Guide](library-author.md). If you wish to automatically instrument your application, see the automatic instrumentation documentation for the SDK you wish to use.
For a high-level overview of OpenTelemetry tracing in general and definitions of some common terms, you can refer to the [OpenTelemetry Specification Overview][spec-overview]
_Trace API Specification: <https://github.com/open-telemetry/opentelemetry-specification/blob/v1.6.0/specification/trace/api.md>_
_Trace API Reference: <https://open-telemetry.github.io/opentelemetry-js-api/classes/traceapi.html>_
- [Acquiring a Tracer](#acquiring-a-tracer)
- [Starting and Ending a Span](#starting-and-ending-a-span)
- [Describing a Span](#describing-a-span)
- [Span Relationships](#span-relationships)
- [Span Attributes](#span-attributes)
- [Span Kind](#span-kind)
- [Client](#client)
- [Server](#server)
- [Internal](#internal)
- [Producer](#producer)
- [Consumer](#consumer)
- [Semantic Conventions](#semantic-conventions)
## Acquiring a Tracer
In OpenTelemetry, tracing operations are performed using methods on a _tracer_. You can get a tracer by calling [`getTracer`](https://open-telemetry.github.io/opentelemetry-js-api/classes/traceapi.html#gettracer) on the global tracer provider. `getTracer` takes the name and version of the application or library acquiring the tracer, and provides a tracer which can be used to trace operations.
```typescript
import { trace } from '@opentelemetry/api';
const tracer = trace.getTracer("my-application", "0.1.0");
```
## Starting and Ending a Span
In OpenTelemetry, all _traces_ are composed of [`Spans`](https://open-telemetry.github.io/opentelemetry-js-api/interfaces/span.html). A span describes a single operation with a start time and and end time like a database request, outgoing remote request, or a function invocation. These spans are linked together by parent-child relationships to form a tree. The resultant tree is your trace, and the root of the tree is commonly called the _root span_.
You can create a span by calling [`Tracer#startSpan`](https://open-telemetry.github.io/opentelemetry-js-api/interfaces/tracer.html#startspan). The only required argument to `startSpan` is the _span name_, which should describe the operation being performed with low cardinality.
```typescript
const span = tracer.startSpan("my-span-name");
// do some work
// When a span is ended, it will be exported to a tracing backend
// via the currently registered SDK.
span.end();
```
Most of the time, spans will be used as part of a function which responds to some event like a web request. The following example shows what it might look like to manually trace a function which responds to a get request using an imaginary http server framework.
```typescript
async function onGet(request, response) {
const span = tracer.startSpan("onGet");
try {
// Do some work here
response.send();
// If we get here and nothing has thrown, the request completed successfully
span.setStatus({ code: SpanStatusCode.OK });
} catch (err) {
// When we catch an error, we want to show that an error occurred
span.setStatus({
code: SpanStatusCode.ERROR,
message: err.message,
});
} finally {
// Every span must be ended or it will not be exported
span.end();
}
}
server.on("GET", "/user/:id", onGet);
```
## Describing a Span
Using span relationships, attributes, kind, and the related [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions), we can more accurately describe the span in a way our tracing backend will more easily understand. The following example uses these mechanisms, which are described below.
```typescript
import { NetTransportValues SemanticAttributes } from '@opentelemetry/semantic-conventions';
import { trace, context, SpanKind, SpanStatusCode } from '@opentelemetry/api';
async function onGet(request, response) {
// HTTP semantic conventions determine the span name and attributes for this span
const span = tracer.startSpan(`GET /user/:id`, {
// attributes can be added when the span is started
attributes: {
// Attributes from the HTTP trace semantic conventions
// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md
[SemanticAttributes.HTTP_METHOD]: "GET",
[SemanticAttributes.HTTP_FLAVOR]: "1.1",
[SemanticAttributes.HTTP_URL]: request.url,
[SemanticAttributes.NET_PEER_IP]: "192.0.2.5",
},
// This span represents a remote incoming synchronous request
kind: SpanKind.SERVER
});
const userId = request.params.id;
// Create a new context from the current context which has the span "active"
const ctx = trace.setSpan(context.active(), span);
// Call getUser with the newly created context
//
// context.with calls a function with an associated "active" context. Within
// the function, calling context.active() returns the currently active context.
// If there is no active context, the ROOT_CONTEXT will be returned, which
// has no key-value pairs.
//
// context.with requires at least 2 arguments: a context and a function to be called.
// If a third argument is provided, it will be bound to `this` `this` inside the function.
// Any additional parameters are used as arguments when calling the function.
//
// Return value is the value returned from getUser
// | Context to be used as the "active" context
// | | Function to be called
// | | | Object assigned to this during function execution
// | | | | Passed as the first argument to getUser
// | | | | |
// V V V V V
const user = await context.with(ctx, getUser, undefined, userId);
// Attributes may also be added after the span is started.
// http.status_code is required by the HTTP trace semantic conventions
span.setAttribute("http.status_code", 200);
response.send(user.toJson());
span.setStatus({
code: SpanStatusCode.OK,
});
span.end();
// Attributes MAY NOT be added after the span ends
span.setAttribute("my.attribute", false); // this does nothing
}
async function getUser(userId) {
// when this span is created, it will automatically use the span from the context as its parent
const span = tracer.startSpan("SELECT ShopDb.Users", {
attributes: {
// Attributes from the database trace semantic conventions
// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md
[SemanticAttributes.DB_SYSTEM]: "mysql",
[SemanticAttributes.DB_CONNECTION_STRING]: "Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;",
[SemanticAttributes.DB_USER]: "app_user",
[SemanticAttributes.NET_PEER_NAME]: "shopdb.example.com",
[SemanticAttributes.NET_PEER_IP]: "192.0.2.12",
[SemanticAttributes.NET_PEER_PORT]: 3306,
[SemanticAttributes.NET_TRANSPORT]: NetTransportValues.IP_TCP,
[SemanticAttributes.DB_NAME]: "ShopDb",
[SemanticAttributes.DB_STATEMENT]: `Select * from Users WHERE user_id = ${userId}`,
[SemanticAttributes.DB_OPERATION]: "SELECT",
[SemanticAttributes.DB_SQL_TABLE]: "Users",
},
kind: SpanKind.CLIENT,
});
const user = await db.select("Users", { id: userId });
span.setStatus({
code: SpanStatusCode.OK,
});
span.end();
return user;
}
server.on("GET", "/user/:id", onGet);
```
### Span Relationships
One of the most important aspects of spans is their relationships to each other. For instance, if one span describes an incoming request which makes a database call, it is recommended to trace the database call as a separate span which is a child of the original request span. In order to do this, when we create a span we can tell OpenTelemetry which span to use as its parent using a mechanism called _Context_.
Context is a very important part of the OpenTelemetry API which cannot be adequately explained in a single paragraph. To read more about context, see the [context documentation](context.md).
### Span Attributes
While name, start time, end time, and status are the minimum information required to trace an operation, most of the time they will not be enough information on their own to effectively observe an application. To solve this, OpenTelemetry uses _Span Attributes_. Span attributes are an object with string keys and string, number, or boolean values which describe the span. For example, we can use the span attributes to add route and http response code information to the example above.
### Span Kind
When a span is created, it is one of `Client`, `Server`, `Internal`, `Producer`, or `Consumer`. This span kind provides a hint to the tracing backend as to how the trace should be assembled. According to the OpenTelemetry specification, the parent of a server span is always a client span, and the child of a client span is always a server span. Similarly, the parent of a consumer span is always a producer and the child of a producer span is always a consumer. If not provided, the span kind is assumed to be internal.
For more information regarding SpanKind, see <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind>.
#### Client
Client spans represent a synchronous outgoing remote call such as an outgoing HTTP request or database call. Note that in this context, "synchronous" does not refer to `async/await`, but to the fact that it is not queued for later processing.
#### Server
Server spans represent a synchronous incoming remote call such as an incoming HTTP request or remote procedure call.
#### Internal
Internal spans represent operations which do not cross a process boundary. Things like instrumenting a function call or an express middleware may use internal spans.
#### Producer
Producer spans represent the creation of a job which may be asynchronously processed later. It may be a remote job such as one inserted into a job queue or a local job handled by an event listener.
#### Consumer
Consumer spans represent the processing of a job created by a producer and may start long after the producer span has already ended.
### Semantic Conventions
One problem with span names and attributes is recognizing, categorizing, and analyzing them in your tracing backend. Between different applications, libraries, and tracing backends there might be different names and expected values for various attributes. For example, your application may use `http.status` to describe the HTTP status code, but a library you use may use `http.status_code`. In order to solve this problem, OpenTelemetry uses a library of semantic conventions which describe the name and attributes which should be used for specific types of spans. The use of semantic conventions is always recommended where applicable, but they are merely conventions. For example, you may find that some name other than the name suggested by the semantic conventions more accurately describes your span, you may decide not to include a span attribute which is suggested by semantic conventions for privacy reasons, or you may wish to add a custom attribute which isn't covered by semantic conventions. All of these cases are fine, but please keep in mind that if you stray from the semantic conventions, the categorization of spans in your tracing backend may be affected.
_See the current trace semantic conventions in the OpenTelemetry Specification repository: <https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions>_
[spec-overview]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md

31
api/karma.base.js Normal file
View File

@ -0,0 +1,31 @@
/*!
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
module.exports = {
listenAddress: 'localhost',
hostname: 'localhost',
browsers: ['ChromeHeadless'],
frameworks: ['mocha'],
coverageIstanbulReporter: {
reports: ['html', 'json'],
dir: '.nyc_output',
fixWebpackSourcePaths: true
},
reporters: ['spec', 'coverage-istanbul'],
files: ['test/index-webpack.ts'],
preprocessors: { 'test/index-webpack.ts': ['webpack'] },
webpackMiddleware: { noInfo: true }
};

8
api/karma.conf.js Normal file
View File

@ -0,0 +1,8 @@
const karmaWebpackConfig = require('./karma.webpack');
const karmaBaseConfig = require('./karma.base');
module.exports = (config) => {
config.set(Object.assign({}, karmaBaseConfig, {
webpack: karmaWebpackConfig
}))
};

43
api/karma.webpack.js Normal file
View File

@ -0,0 +1,43 @@
/*!
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
const webpackNodePolyfills = require('./webpack.node-polyfills.js');
// This is the webpack configuration for browser Karma tests with coverage.
module.exports = {
mode: 'development',
target: 'web',
output: { filename: 'bundle.js' },
resolve: { extensions: ['.ts', '.js'] },
devtool: 'inline-source-map',
module: {
rules: [
{ test: /\.ts$/, use: 'ts-loader' },
{
enforce: 'post',
exclude: /(node_modules|\.test\.[tj]sx?$)/,
test: /\.ts$/,
use: {
loader: 'istanbul-instrumenter-loader',
options: { esModules: true }
}
},
// This setting configures Node polyfills for the browser that will be
// added to the webpack bundle for Karma tests.
{ parser: { node: webpackNodePolyfills } }
]
}
};

90
api/package.json Normal file
View File

@ -0,0 +1,90 @@
{
"name": "@opentelemetry/api",
"version": "1.2.0",
"description": "Public API for OpenTelemetry",
"main": "build/src/index.js",
"module": "build/esm/index.js",
"types": "build/src/index.d.ts",
"browser": {
"./src/platform/index.ts": "./src/platform/browser/index.ts",
"./build/esm/platform/index.js": "./build/esm/platform/browser/index.js",
"./build/src/platform/index.js": "./build/src/platform/browser/index.js"
},
"repository": "https://github.com/open-telemetry/opentelemetry-js-api.git",
"scripts": {
"clean": "tsc --build --clean tsconfig.json tsconfig.esm.json",
"codecov:browser": "nyc report --reporter=json && codecov -f coverage/*.json -p .",
"codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p .",
"precompile": "npm run version",
"compile": "tsc --build tsconfig.json tsconfig.esm.json",
"docs": "typedoc",
"docs:deploy": "gh-pages --dist docs/out",
"docs:test": "linkinator docs/out --silent && linkinator docs/*.md *.md --markdown --silent",
"lint:fix": "eslint src test --ext .ts --fix",
"lint": "eslint src test --ext .ts",
"test:browser": "nyc karma start --single-run",
"test": "nyc ts-mocha -p tsconfig.json test/**/*.test.ts",
"cycle-check": "dpdm --exit-code circular:1 src/index.ts",
"version": "node scripts/version-update.js",
"prewatch": "npm run version",
"watch": "tsc --build --watch"
},
"keywords": [
"opentelemetry",
"nodejs",
"browser",
"tracing",
"profiling",
"stats",
"monitoring"
],
"author": "OpenTelemetry Authors",
"license": "Apache-2.0",
"engines": {
"node": ">=8.0.0"
},
"files": [
"build/esm/**/*.js",
"build/esm/**/*.js.map",
"build/esm/**/*.d.ts",
"build/src/**/*.js",
"build/src/**/*.js.map",
"build/src/**/*.d.ts",
"LICENSE",
"README.md"
],
"publishConfig": {
"access": "public"
},
"devDependencies": {
"@types/mocha": "8.2.2",
"@types/node": "14.17.4",
"@types/sinon": "10.0.2",
"@types/webpack-env": "1.16.0",
"@typescript-eslint/eslint-plugin": "5.0.0",
"@typescript-eslint/parser": "5.0.0",
"codecov": "3.8.2",
"dpdm": "3.7.1",
"eslint": "7.32.0",
"eslint-plugin-header": "3.1.1",
"eslint-plugin-node": "11.1.0",
"gh-pages": "3.2.0",
"istanbul-instrumenter-loader": "3.0.1",
"karma": "5.2.3",
"karma-chrome-launcher": "3.1.0",
"karma-coverage-istanbul-reporter": "3.0.3",
"karma-mocha": "2.0.1",
"karma-spec-reporter": "0.0.32",
"karma-webpack": "4.0.2",
"lerna-changelog": "1.0.1",
"linkinator": "2.13.6",
"mocha": "7.2.0",
"nyc": "15.1.0",
"sinon": "11.1.1",
"ts-loader": "8.2.0",
"ts-mocha": "8.0.0",
"typedoc": "0.21.2",
"typescript": "4.3.5",
"webpack": "4.46.0"
}
}

25
api/renovate.json Normal file
View File

@ -0,0 +1,25 @@
{
"extends": [
"config:base"
],
"packageRules": [
{
"groupName": "all non-major dependencies",
"updateTypes": ["patch", "minor"],
"groupSlug": "all-minor-patch"
}
],
"ignoreDeps": [
"gcp-metadata",
"got",
"mocha"
],
"assignees": [
"@dyladan",
"@vmarchaud"
],
"schedule": [
"before 3am on Friday"
],
"labels": ["dependencies"]
}

48
api/scripts/version-update.js Normal file
View File

@ -0,0 +1,48 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
const fs = require('fs');
const os = require('os');
const path = require('path');
const appRoot = process.cwd();
const packageJsonUrl = path.resolve(`${appRoot}/package.json`);
const pjson = require(packageJsonUrl);
const content = `/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// this is autogenerated file, see scripts/version-update.js
export const VERSION = '${pjson.version}';
`;
const fileUrl = path.join(appRoot, "src", "version.ts")
fs.writeFileSync(fileUrl, content);

99
api/src/api/context.ts Normal file
View File

@ -0,0 +1,99 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { NoopContextManager } from '../context/NoopContextManager';
import { Context, ContextManager } from '../context/types';
import {
getGlobal,
registerGlobal,
unregisterGlobal,
} from '../internal/global-utils';
import { DiagAPI } from './diag';
const API_NAME = 'context';
const NOOP_CONTEXT_MANAGER = new NoopContextManager();
/**
* Singleton object which represents the entry point to the OpenTelemetry Context API
*/
export class ContextAPI {
private static _instance?: ContextAPI;
/** Empty private constructor prevents end users from constructing a new instance of the API */
private constructor() {}
/** Get the singleton instance of the Context API */
public static getInstance(): ContextAPI {
if (!this._instance) {
this._instance = new ContextAPI();
}
return this._instance;
}
/**
* Set the current context manager.
*
* @returns true if the context manager was successfully registered, else false
*/
public setGlobalContextManager(contextManager: ContextManager): boolean {
return registerGlobal(API_NAME, contextManager, DiagAPI.instance());
}
/**
* Get the currently active context
*/
public active(): Context {
return this._getContextManager().active();
}
/**
* Execute a function with an active context
*
* @param context context to be active during function execution
* @param fn function to execute in a context
* @param thisArg optional receiver to be used for calling fn
* @param args optional arguments forwarded to fn
*/
public with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(
context: Context,
fn: F,
thisArg?: ThisParameterType<F>,
...args: A
): ReturnType<F> {
return this._getContextManager().with(context, fn, thisArg, ...args);
}
/**
* Bind a context to a target function or event emitter
*
* @param context context to bind to the event emitter or function. Defaults to the currently active context
* @param target function or event emitter to bind
*/
public bind<T>(context: Context, target: T): T {
return this._getContextManager().bind(context, target);
}
private _getContextManager(): ContextManager {
return getGlobal(API_NAME) || NOOP_CONTEXT_MANAGER;
}
/** Disable and remove the global context manager */
public disable() {
this._getContextManager().disable();
unregisterGlobal(API_NAME, DiagAPI.instance());
}
}

139
api/src/api/diag.ts Normal file
View File

@ -0,0 +1,139 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { DiagComponentLogger } from '../diag/ComponentLogger';
import { createLogLevelDiagLogger } from '../diag/internal/logLevelLogger';
import {
ComponentLoggerOptions,
DiagLogFunction,
DiagLogger,
DiagLogLevel,
} from '../diag/types';
import {
getGlobal,
registerGlobal,
unregisterGlobal,
} from '../internal/global-utils';
const API_NAME = 'diag';
/**
* Singleton object which represents the entry point to the OpenTelemetry internal
* diagnostic API
*/
export class DiagAPI implements DiagLogger {
private static _instance?: DiagAPI;
/** Get the singleton instance of the DiagAPI API */
public static instance(): DiagAPI {
if (!this._instance) {
this._instance = new DiagAPI();
}
return this._instance;
}
/**
* Private internal constructor
* @private
*/
private constructor() {
function _logProxy(funcName: keyof DiagLogger): DiagLogFunction {
return function (...args) {
const logger = getGlobal('diag');
// shortcut if logger not set
if (!logger) return;
return logger[funcName](...args);
};
}
// Using self local variable for minification purposes as 'this' cannot be minified
const self = this;
// DiagAPI specific functions
self.setLogger = (
logger: DiagLogger,
logLevel: DiagLogLevel = DiagLogLevel.INFO
) => {
if (logger === self) {
// There isn't much we can do here.
// Logging to the console might break the user application.
// Try to log to self. If a logger was previously registered it will receive the log.
const err = new Error(
'Cannot use diag as the logger for itself. Please use a DiagLogger implementation like ConsoleDiagLogger or a custom implementation'
);
self.error(err.stack ?? err.message);
return false;
}
const oldLogger = getGlobal('diag');
const newLogger = createLogLevelDiagLogger(logLevel, logger);
// There already is an logger registered. We'll let it know before overwriting it.
if (oldLogger) {
const stack = new Error().stack ?? '<failed to generate stacktrace>';
oldLogger.warn(`Current logger will be overwritten from ${stack}`);
newLogger.warn(
`Current logger will overwrite one already registered from ${stack}`
);
}
return registerGlobal('diag', newLogger, self, true);
};
self.disable = () => {
unregisterGlobal(API_NAME, self);
};
self.createComponentLogger = (options: ComponentLoggerOptions) => {
return new DiagComponentLogger(options);
};
self.verbose = _logProxy('verbose');
self.debug = _logProxy('debug');
self.info = _logProxy('info');
self.warn = _logProxy('warn');
self.error = _logProxy('error');
}
/**
* Set the global DiagLogger and DiagLogLevel.
* If a global diag logger is already set, this will override it.
*
* @param logger - [Optional] The DiagLogger instance to set as the default logger.
* @param logLevel - [Optional] The DiagLogLevel used to filter logs sent to the logger. If not provided it will default to INFO.
* @returns true if the logger was successfully registered, else false
*/
public setLogger!: (logger: DiagLogger, logLevel?: DiagLogLevel) => boolean;
/**
*
*/
public createComponentLogger!: (
options: ComponentLoggerOptions
) => DiagLogger;
// DiagLogger implementation
public verbose!: DiagLogFunction;
public debug!: DiagLogFunction;
public info!: DiagLogFunction;
public warn!: DiagLogFunction;
public error!: DiagLogFunction;
/**
* Unregister the global logger and return to Noop
*/
public disable!: () => void;
}

122
api/src/api/propagation.ts Normal file
View File

@ -0,0 +1,122 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from '../context/types';
import {
getGlobal,
registerGlobal,
unregisterGlobal,
} from '../internal/global-utils';
import { NoopTextMapPropagator } from '../propagation/NoopTextMapPropagator';
import {
defaultTextMapGetter,
defaultTextMapSetter,
TextMapGetter,
TextMapPropagator,
TextMapSetter,
} from '../propagation/TextMapPropagator';
import {
getBaggage,
setBaggage,
deleteBaggage,
} from '../baggage/context-helpers';
import { createBaggage } from '../baggage/utils';
import { DiagAPI } from './diag';
const API_NAME = 'propagation';
const NOOP_TEXT_MAP_PROPAGATOR = new NoopTextMapPropagator();
/**
* Singleton object which represents the entry point to the OpenTelemetry Propagation API
*/
export class PropagationAPI {
private static _instance?: PropagationAPI;
/** Empty private constructor prevents end users from constructing a new instance of the API */
private constructor() {}
/** Get the singleton instance of the Propagator API */
public static getInstance(): PropagationAPI {
if (!this._instance) {
this._instance = new PropagationAPI();
}
return this._instance;
}
/**
* Set the current propagator.
*
* @returns true if the propagator was successfully registered, else false
*/
public setGlobalPropagator(propagator: TextMapPropagator): boolean {
return registerGlobal(API_NAME, propagator, DiagAPI.instance());
}
/**
* Inject context into a carrier to be propagated inter-process
*
* @param context Context carrying tracing data to inject
* @param carrier carrier to inject context into
* @param setter Function used to set values on the carrier
*/
public inject<Carrier>(
context: Context,
carrier: Carrier,
setter: TextMapSetter<Carrier> = defaultTextMapSetter
): void {
return this._getGlobalPropagator().inject(context, carrier, setter);
}
/**
* Extract context from a carrier
*
* @param context Context which the newly created context will inherit from
* @param carrier Carrier to extract context from
* @param getter Function used to extract keys from a carrier
*/
public extract<Carrier>(
context: Context,
carrier: Carrier,
getter: TextMapGetter<Carrier> = defaultTextMapGetter
): Context {
return this._getGlobalPropagator().extract(context, carrier, getter);
}
/**
* Return a list of all fields which may be used by the propagator.
*/
public fields(): string[] {
return this._getGlobalPropagator().fields();
}
/** Remove the global propagator */
public disable() {
unregisterGlobal(API_NAME, DiagAPI.instance());
}
public createBaggage = createBaggage;
public getBaggage = getBaggage;
public setBaggage = setBaggage;
public deleteBaggage = deleteBaggage;
private _getGlobalPropagator(): TextMapPropagator {
return getGlobal(API_NAME) || NOOP_TEXT_MAP_PROPAGATOR;
}
}

113
api/src/api/trace.ts Normal file
View File

@ -0,0 +1,113 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import {
getGlobal,
registerGlobal,
unregisterGlobal,
} from '../internal/global-utils';
import { ProxyTracerProvider } from '../trace/ProxyTracerProvider';
import {
isSpanContextValid,
wrapSpanContext,
} from '../trace/spancontext-utils';
import { Tracer } from '../trace/tracer';
import { TracerProvider } from '../trace/tracer_provider';
import {
deleteSpan,
getActiveSpan,
getSpan,
getSpanContext,
setSpan,
setSpanContext,
} from '../trace/context-utils';
import { DiagAPI } from './diag';
const API_NAME = 'trace';
/**
* Singleton object which represents the entry point to the OpenTelemetry Tracing API
*/
export class TraceAPI {
private static _instance?: TraceAPI;
private _proxyTracerProvider = new ProxyTracerProvider();
/** Empty private constructor prevents end users from constructing a new instance of the API */
private constructor() {}
/** Get the singleton instance of the Trace API */
public static getInstance(): TraceAPI {
if (!this._instance) {
this._instance = new TraceAPI();
}
return this._instance;
}
/**
* Set the current global tracer.
*
* @returns true if the tracer provider was successfully registered, else false
*/
public setGlobalTracerProvider(provider: TracerProvider): boolean {
const success = registerGlobal(
API_NAME,
this._proxyTracerProvider,
DiagAPI.instance()
);
if (success) {
this._proxyTracerProvider.setDelegate(provider);
}
return success;
}
/**
* Returns the global tracer provider.
*/
public getTracerProvider(): TracerProvider {
return getGlobal(API_NAME) || this._proxyTracerProvider;
}
/**
* Returns a tracer from the global tracer provider.
*/
public getTracer(name: string, version?: string): Tracer {
return this.getTracerProvider().getTracer(name, version);
}
/** Remove the global tracer provider */
public disable() {
unregisterGlobal(API_NAME, DiagAPI.instance());
this._proxyTracerProvider = new ProxyTracerProvider();
}
public wrapSpanContext = wrapSpanContext;
public isSpanContextValid = isSpanContextValid;
public deleteSpan = deleteSpan;
public getSpan = getSpan;
public getActiveSpan = getActiveSpan;
public getSpanContext = getSpanContext;
public setSpan = setSpan;
public setSpanContext = setSpanContext;
}

53
api/src/baggage/context-helpers.ts Normal file
View File

@ -0,0 +1,53 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { createContextKey } from '../context/context';
import { Context } from '../context/types';
import { Baggage } from './types';
/**
* Baggage key
*/
const BAGGAGE_KEY = createContextKey('OpenTelemetry Baggage Key');
/**
* Retrieve the current baggage from the given context
*
* @param {Context} Context that manage all context values
* @returns {Baggage} Extracted baggage from the context
*/
export function getBaggage(context: Context): Baggage | undefined {
return (context.getValue(BAGGAGE_KEY) as Baggage) || undefined;
}
/**
* Store a baggage in the given context
*
* @param {Context} Context that manage all context values
* @param {Baggage} baggage that will be set in the actual context
*/
export function setBaggage(context: Context, baggage: Baggage): Context {
return context.setValue(BAGGAGE_KEY, baggage);
}
/**
* Delete the baggage stored in the given context
*
* @param {Context} Context that manage all context values
*/
export function deleteBaggage(context: Context): Context {
return context.deleteValue(BAGGAGE_KEY);
}

62
api/src/baggage/internal/baggage-impl.ts Normal file
View File

@ -0,0 +1,62 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import type { Baggage, BaggageEntry } from '../types';
export class BaggageImpl implements Baggage {
private _entries: Map<string, BaggageEntry>;
constructor(entries?: Map<string, BaggageEntry>) {
this._entries = entries ? new Map(entries) : new Map();
}
getEntry(key: string): BaggageEntry | undefined {
const entry = this._entries.get(key);
if (!entry) {
return undefined;
}
return Object.assign({}, entry);
}
getAllEntries(): [string, BaggageEntry][] {
return Array.from(this._entries.entries()).map(([k, v]) => [k, v]);
}
setEntry(key: string, entry: BaggageEntry): BaggageImpl {
const newBaggage = new BaggageImpl(this._entries);
newBaggage._entries.set(key, entry);
return newBaggage;
}
removeEntry(key: string): BaggageImpl {
const newBaggage = new BaggageImpl(this._entries);
newBaggage._entries.delete(key);
return newBaggage;
}
removeEntries(...keys: string[]): BaggageImpl {
const newBaggage = new BaggageImpl(this._entries);
for (const key of keys) {
newBaggage._entries.delete(key);
}
return newBaggage;
}
clear(): BaggageImpl {
return new BaggageImpl();
}
}

20
api/src/baggage/internal/symbol.ts Normal file
View File

@ -0,0 +1,20 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Symbol used to make BaggageEntryMetadata an opaque type
*/
export const baggageEntryMetadataSymbol = Symbol('BaggageEntryMetadata');

97
api/src/baggage/types.ts Normal file
View File

@ -0,0 +1,97 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { baggageEntryMetadataSymbol } from './internal/symbol';
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export interface BaggageEntry {
/** `String` value of the `BaggageEntry`. */
value: string;
/**
* Metadata is an optional string property defined by the W3C baggage specification.
* It currently has no special meaning defined by the specification.
*/
metadata?: BaggageEntryMetadata;
}
/**
* Serializable Metadata defined by the W3C baggage specification.
* It currently has no special meaning defined by the OpenTelemetry or W3C.
*/
export type BaggageEntryMetadata = { toString(): string } & {
__TYPE__: typeof baggageEntryMetadataSymbol;
};
/**
* Baggage represents collection of key-value pairs with optional metadata.
* Each key of Baggage is associated with exactly one value.
* Baggage may be used to annotate and enrich telemetry data.
*/
export interface Baggage {
/**
* Get an entry from Baggage if it exists
*
* @param key The key which identifies the BaggageEntry
*/
getEntry(key: string): BaggageEntry | undefined;
/**
* Get a list of all entries in the Baggage
*/
getAllEntries(): [string, BaggageEntry][];
/**
* Returns a new baggage with the entries from the current bag and the specified entry
*
* @param key string which identifies the baggage entry
* @param entry BaggageEntry for the given key
*/
setEntry(key: string, entry: BaggageEntry): Baggage;
/**
* Returns a new baggage with the entries from the current bag except the removed entry
*
* @param key key identifying the entry to be removed
*/
removeEntry(key: string): Baggage;
/**
* Returns a new baggage with the entries from the current bag except the removed entries
*
* @param key keys identifying the entries to be removed
*/
removeEntries(...key: string[]): Baggage;
/**
* Returns a new baggage with no entries
*/
clear(): Baggage;
}

57
api/src/baggage/utils.ts Normal file
View File

@ -0,0 +1,57 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { DiagAPI } from '../api/diag';
import { BaggageImpl } from './internal/baggage-impl';
import { baggageEntryMetadataSymbol } from './internal/symbol';
import { Baggage, BaggageEntry, BaggageEntryMetadata } from './types';
const diag = DiagAPI.instance();
/**
* Create a new Baggage with optional entries
*
* @param entries An array of baggage entries the new baggage should contain
*/
export function createBaggage(
entries: Record<string, BaggageEntry> = {}
): Baggage {
return new BaggageImpl(new Map(Object.entries(entries)));
}
/**
* Create a serializable BaggageEntryMetadata object from a string.
*
* @param str string metadata. Format is currently not defined by the spec and has no special meaning.
*
*/
export function baggageEntryMetadataFromString(
str: string
): BaggageEntryMetadata {
if (typeof str !== 'string') {
diag.error(
`Cannot create baggage metadata from unknown type: ${typeof str}`
);
str = '';
}
return {
__TYPE__: baggageEntryMetadataSymbol,
toString() {
return str;
},
};
}

37
api/src/common/Attributes.ts Normal file
View File

@ -0,0 +1,37 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Attributes is a map from string to attribute values.
*
* Note: only the own enumerable keys are counted as valid attribute keys.
*/
export interface Attributes {
[attributeKey: string]: AttributeValue | undefined;
}
/**
* Attribute values may be any non-nullish primitive value except an object.
*
* null or undefined attribute values are invalid and will result in undefined behavior.
*/
export type AttributeValue =
| string
| number
| boolean
| Array<null | undefined | string>
| Array<null | undefined | number>
| Array<null | undefined | boolean>;

47
api/src/common/Exception.ts Normal file
View File

@ -0,0 +1,47 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
interface ExceptionWithCode {
code: string | number;
name?: string;
message?: string;
stack?: string;
}
interface ExceptionWithMessage {
code?: string | number;
message: string;
name?: string;
stack?: string;
}
interface ExceptionWithName {
code?: string | number;
message?: string;
name: string;
stack?: string;
}
/**
* Defines Exception.
*
* string or an object with one of (message or name or code) and optional stack
*/
export type Exception =
| ExceptionWithCode
| ExceptionWithMessage
| ExceptionWithName
| string;

35
api/src/common/Time.ts Normal file
View File

@ -0,0 +1,35 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Defines High-Resolution Time.
*
* The first number, HrTime[0], is UNIX Epoch time in seconds since 00:00:00 UTC on 1 January 1970.
* The second number, HrTime[1], represents the partial second elapsed since Unix Epoch time represented by first number in nanoseconds.
* For example, 2021-01-01T12:30:10.150Z in UNIX Epoch time in milliseconds is represented as 1609504210150.
* The first number is calculated by converting and truncating the Epoch time in milliseconds to seconds:
* HrTime[0] = Math.trunc(1609504210150 / 1000) = 1609504210.
* The second number is calculated by converting the digits after the decimal point of the subtraction, (1609504210150 / 1000) - HrTime[0], to nanoseconds:
* HrTime[1] = Number((1609504210.150 - HrTime[0]).toFixed(9)) * 1e9 = 150000000.
* This is represented in HrTime format as [1609504210, 150000000].
*/
export type HrTime = [number, number];
/**
* Defines TimeInput.
*
* hrtime, epoch milliseconds, performance.now() or Date
*/
export type TimeInput = HrTime | number | Date;

45
api/src/context/NoopContextManager.ts Normal file
View File

@ -0,0 +1,45 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ROOT_CONTEXT } from './context';
import * as types from './types';
export class NoopContextManager implements types.ContextManager {
active(): types.Context {
return ROOT_CONTEXT;
}
with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(
_context: types.Context,
fn: F,
thisArg?: ThisParameterType<F>,
...args: A
): ReturnType<F> {
return fn.call(thisArg, ...args);
}
bind<T>(_context: types.Context, target: T): T {
return target;
}
enable(): this {
return this;
}
disable(): this {
return this;
}
}

85
api/src/context/context.ts Normal file
View File

@ -0,0 +1,85 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from './types';
/** Get a key to uniquely identify a context value */
export function createContextKey(description: string) {
// The specification states that for the same input, multiple calls should
// return different keys. Due to the nature of the JS dependency management
// system, this creates problems where multiple versions of some package
// could hold different keys for the same property.
//
// Therefore, we use Symbol.for which returns the same key for the same input.
return Symbol.for(description);
}
class BaseContext implements Context {
private _currentContext!: Map<symbol, unknown>;
/**
* Construct a new context which inherits values from an optional parent context.
*
* @param parentContext a context from which to inherit values
*/
constructor(parentContext?: Map<symbol, unknown>) {
// for minification
const self = this;
self._currentContext = parentContext ? new Map(parentContext) : new Map();
self.getValue = (key: symbol) => self._currentContext.get(key);
self.setValue = (key: symbol, value: unknown): Context => {
const context = new BaseContext(self._currentContext);
context._currentContext.set(key, value);
return context;
};
self.deleteValue = (key: symbol): Context => {
const context = new BaseContext(self._currentContext);
context._currentContext.delete(key);
return context;
};
}
/**
* Get a value from the context.
*
* @param key key which identifies a context value
*/
public getValue!: (key: symbol) => unknown;
/**
* Create a new context which inherits from this context and has
* the given key set to the given value.
*
* @param key context key for which to set the value
* @param value value to set for the given key
*/
public setValue!: (key: symbol, value: unknown) => Context;
/**
* Return a new context which inherits from this context but does
* not contain a value for the given key.
*
* @param key context key for which to clear a value
*/
public deleteValue!: (key: symbol) => Context;
}
/** The root context is used as the default parent context when there is no active context */
export const ROOT_CONTEXT: Context = new BaseContext();

79
api/src/context/types.ts Normal file
View File

@ -0,0 +1,79 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export interface Context {
/**
* Get a value from the context.
*
* @param key key which identifies a context value
*/
getValue(key: symbol): unknown;
/**
* Create a new context which inherits from this context and has
* the given key set to the given value.
*
* @param key context key for which to set the value
* @param value value to set for the given key
*/
setValue(key: symbol, value: unknown): Context;
/**
* Return a new context which inherits from this context but does
* not contain a value for the given key.
*
* @param key context key for which to clear a value
*/
deleteValue(key: symbol): Context;
}
export interface ContextManager {
/**
* Get the current active context
*/
active(): Context;
/**
* Run the fn callback with object set as the current active context
* @param context Any object to set as the current active context
* @param fn A callback to be immediately run within a specific context
* @param thisArg optional receiver to be used for calling fn
* @param args optional arguments forwarded to fn
*/
with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(
context: Context,
fn: F,
thisArg?: ThisParameterType<F>,
...args: A
): ReturnType<F>;
/**
* Bind an object as the current context (or a specific one)
* @param [context] Optionally specify the context which you want to assign
* @param target Any object to which a context need to be set
*/
bind<T>(context: Context, target: T): T;
/**
* Enable context management
*/
enable(): this;
/**
* Disable context management
*/
disable(): this;
}

70
api/src/diag/ComponentLogger.ts Normal file
View File

@ -0,0 +1,70 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { getGlobal } from '../internal/global-utils';
import { ComponentLoggerOptions, DiagLogger, DiagLogFunction } from './types';
/**
* Component Logger which is meant to be used as part of any component which
* will add automatically additional namespace in front of the log message.
* It will then forward all message to global diag logger
* @example
* const cLogger = diag.createComponentLogger({ namespace: '@opentelemetry/instrumentation-http' });
* cLogger.debug('test');
* // @opentelemetry/instrumentation-http test
*/
export class DiagComponentLogger implements DiagLogger {
private _namespace: string;
constructor(props: ComponentLoggerOptions) {
this._namespace = props.namespace || 'DiagComponentLogger';
}
public debug(...args: any[]): void {
return logProxy('debug', this._namespace, args);
}
public error(...args: any[]): void {
return logProxy('error', this._namespace, args);
}
public info(...args: any[]): void {
return logProxy('info', this._namespace, args);
}
public warn(...args: any[]): void {
return logProxy('warn', this._namespace, args);
}
public verbose(...args: any[]): void {
return logProxy('verbose', this._namespace, args);
}
}
function logProxy(
funcName: keyof DiagLogger,
namespace: string,
args: any
): void {
const logger = getGlobal('diag');
// shortcut if logger not set
if (!logger) {
return;
}
args.unshift(namespace);
return logger[funcName](...(args as Parameters<DiagLogFunction>));
}

92
api/src/diag/consoleLogger.ts Normal file
View File

@ -0,0 +1,92 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { DiagLogger, DiagLogFunction } from './types';
type ConsoleMapKeys = 'error' | 'warn' | 'info' | 'debug' | 'trace';
const consoleMap: { n: keyof DiagLogger; c: ConsoleMapKeys }[] = [
{ n: 'error', c: 'error' },
{ n: 'warn', c: 'warn' },
{ n: 'info', c: 'info' },
{ n: 'debug', c: 'debug' },
{ n: 'verbose', c: 'trace' },
];
/**
* A simple Immutable Console based diagnostic logger which will output any messages to the Console.
* If you want to limit the amount of logging to a specific level or lower use the
* {@link createLogLevelDiagLogger}
*/
export class DiagConsoleLogger implements DiagLogger {
constructor() {
function _consoleFunc(funcName: ConsoleMapKeys): DiagLogFunction {
return function (...args) {
if (console) {
// Some environments only expose the console when the F12 developer console is open
// eslint-disable-next-line no-console
let theFunc = console[funcName];
if (typeof theFunc !== 'function') {
// Not all environments support all functions
// eslint-disable-next-line no-console
theFunc = console.log;
}
// One last final check
if (typeof theFunc === 'function') {
return theFunc.apply(console, args);
}
}
};
}
for (let i = 0; i < consoleMap.length; i++) {
this[consoleMap[i].n] = _consoleFunc(consoleMap[i].c);
}
}
/** Log an error scenario that was not expected and caused the requested operation to fail. */
public error!: DiagLogFunction;
/**
* Log a warning scenario to inform the developer of an issues that should be investigated.
* The requested operation may or may not have succeeded or completed.
*/
public warn!: DiagLogFunction;
/**
* Log a general informational message, this should not affect functionality.
* This is also the default logging level so this should NOT be used for logging
* debugging level information.
*/
public info!: DiagLogFunction;
/**
* Log a general debug message that can be useful for identifying a failure.
* Information logged at this level may include diagnostic details that would
* help identify a failure scenario. Useful scenarios would be to log the execution
* order of async operations
*/
public debug!: DiagLogFunction;
/**
* Log a detailed (verbose) trace level logging that can be used to identify failures
* where debug level logging would be insufficient, this level of tracing can include
* input and output parameters and as such may include PII information passing through
* the API. As such it is recommended that this level of tracing should not be enabled
* in a production environment.
*/
public verbose!: DiagLogFunction;
}

18
api/src/diag/index.ts Normal file
View File

@ -0,0 +1,18 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export * from './consoleLogger';
export * from './types';

51
api/src/diag/internal/logLevelLogger.ts Normal file
View File

@ -0,0 +1,51 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { DiagLogFunction, DiagLogger, DiagLogLevel } from '../types';
export function createLogLevelDiagLogger(
maxLevel: DiagLogLevel,
logger: DiagLogger
): DiagLogger {
if (maxLevel < DiagLogLevel.NONE) {
maxLevel = DiagLogLevel.NONE;
} else if (maxLevel > DiagLogLevel.ALL) {
maxLevel = DiagLogLevel.ALL;
}
// In case the logger is null or undefined
logger = logger || {};
function _filterFunc(
funcName: keyof DiagLogger,
theLevel: DiagLogLevel
): DiagLogFunction {
const theFunc = logger[funcName];
if (typeof theFunc === 'function' && maxLevel >= theLevel) {
return theFunc.bind(logger);
}
return function () {};
}
return {
error: _filterFunc('error', DiagLogLevel.ERROR),
warn: _filterFunc('warn', DiagLogLevel.WARN),
info: _filterFunc('info', DiagLogLevel.INFO),
debug: _filterFunc('debug', DiagLogLevel.DEBUG),
verbose: _filterFunc('verbose', DiagLogLevel.VERBOSE),
};
}

34
api/src/diag/internal/noopLogger.ts Normal file
View File

@ -0,0 +1,34 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { DiagLogger } from '../types';
function noopLogFunction() {}
/**
* Returns a No-Op Diagnostic logger where all messages do nothing.
* @implements {@link DiagLogger}
* @returns {DiagLogger}
*/
export function createNoopDiagLogger(): DiagLogger {
return {
verbose: noopLogFunction,
debug: noopLogFunction,
info: noopLogFunction,
warn: noopLogFunction,
error: noopLogFunction,
};
}

98
api/src/diag/types.ts Normal file
View File

@ -0,0 +1,98 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export type DiagLogFunction = (message: string, ...args: unknown[]) => void;
/**
* Defines an internal diagnostic logger interface which is used to log internal diagnostic
* messages, you can set the default diagnostic logger via the {@link DiagAPI} setLogger function.
* API provided implementations include :-
* - a No-Op {@link createNoopDiagLogger}
* - a {@link DiagLogLevel} filtering wrapper {@link createLogLevelDiagLogger}
* - a general Console {@link DiagConsoleLogger} version.
*/
export interface DiagLogger {
/** Log an error scenario that was not expected and caused the requested operation to fail. */
error: DiagLogFunction;
/**
* Log a warning scenario to inform the developer of an issues that should be investigated.
* The requested operation may or may not have succeeded or completed.
*/
warn: DiagLogFunction;
/**
* Log a general informational message, this should not affect functionality.
* This is also the default logging level so this should NOT be used for logging
* debugging level information.
*/
info: DiagLogFunction;
/**
* Log a general debug message that can be useful for identifying a failure.
* Information logged at this level may include diagnostic details that would
* help identify a failure scenario.
* For example: Logging the order of execution of async operations.
*/
debug: DiagLogFunction;
/**
* Log a detailed (verbose) trace level logging that can be used to identify failures
* where debug level logging would be insufficient, this level of tracing can include
* input and output parameters and as such may include PII information passing through
* the API. As such it is recommended that this level of tracing should not be enabled
* in a production environment.
*/
verbose: DiagLogFunction;
}
/**
* Defines the available internal logging levels for the diagnostic logger, the numeric values
* of the levels are defined to match the original values from the initial LogLevel to avoid
* compatibility/migration issues for any implementation that assume the numeric ordering.
*/
export enum DiagLogLevel {
/** Diagnostic Logging level setting to disable all logging (except and forced logs) */
NONE = 0,
/** Identifies an error scenario */
ERROR = 30,
/** Identifies a warning scenario */
WARN = 50,
/** General informational log message */
INFO = 60,
/** General debug log message */
DEBUG = 70,
/**
* Detailed trace level logging should only be used for development, should only be set
* in a development environment.
*/
VERBOSE = 80,
/** Used to set the logging level to include all logging */
ALL = 9999,
}
/**
* Defines options for ComponentLogger
*/
export interface ComponentLoggerOptions {
namespace: string;
}

88
api/src/index.ts Normal file
View File

@ -0,0 +1,88 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export * from './baggage/types';
export { baggageEntryMetadataFromString } from './baggage/utils';
export * from './common/Exception';
export * from './common/Time';
export * from './common/Attributes';
export * from './diag';
export * from './propagation/TextMapPropagator';
export * from './trace/attributes';
export * from './trace/link';
export * from './trace/ProxyTracer';
export * from './trace/ProxyTracerProvider';
export * from './trace/Sampler';
export * from './trace/SamplingResult';
export * from './trace/span_context';
export * from './trace/span_kind';
export * from './trace/span';
export * from './trace/SpanOptions';
export * from './trace/status';
export * from './trace/trace_flags';
export * from './trace/trace_state';
export { createTraceState } from './trace/internal/utils';
export * from './trace/tracer_provider';
export * from './trace/tracer';
export * from './trace/tracer_options';
export {
isSpanContextValid,
isValidTraceId,
isValidSpanId,
} from './trace/spancontext-utils';
export {
INVALID_SPANID,
INVALID_TRACEID,
INVALID_SPAN_CONTEXT,
} from './trace/invalid-span-constants';
export * from './context/context';
export * from './context/types';
import { ContextAPI } from './api/context';
export type { ContextAPI } from './api/context';
/** Entrypoint for context API */
export const context = ContextAPI.getInstance();
import { TraceAPI } from './api/trace';
export type { TraceAPI } from './api/trace';
/** Entrypoint for trace API */
export const trace = TraceAPI.getInstance();
import { PropagationAPI } from './api/propagation';
export type { PropagationAPI } from './api/propagation';
/** Entrypoint for propagation API */
export const propagation = PropagationAPI.getInstance();
import { DiagAPI } from './api/diag';
export type { DiagAPI } from './api/diag';
/**
* Entrypoint for Diag API.
* Defines Diagnostic handler used for internal diagnostic logging operations.
* The default provides a Noop DiagLogger implementation which may be changed via the
* diag.setLogger(logger: DiagLogger) function.
*/
export const diag = DiagAPI.instance();
export default {
trace,
context,
propagation,
diag,
};

102
api/src/internal/global-utils.ts Normal file
View File

@ -0,0 +1,102 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ContextManager } from '../context/types';
import { DiagLogger } from '../diag';
import { _globalThis } from '../platform';
import { TextMapPropagator } from '../propagation/TextMapPropagator';
import type { TracerProvider } from '../trace/tracer_provider';
import { VERSION } from '../version';
import { isCompatible } from './semver';
const major = VERSION.split('.')[0];
const GLOBAL_OPENTELEMETRY_API_KEY = Symbol.for(
`opentelemetry.js.api.${major}`
);
const _global = _globalThis as OTelGlobal;
export function registerGlobal<Type extends keyof OTelGlobalAPI>(
type: Type,
instance: OTelGlobalAPI[Type],
diag: DiagLogger,
allowOverride = false
): boolean {
const api = (_global[GLOBAL_OPENTELEMETRY_API_KEY] = _global[
GLOBAL_OPENTELEMETRY_API_KEY
] ?? {
version: VERSION,
});
if (!allowOverride && api[type]) {
// already registered an API of this type
const err = new Error(
`@opentelemetry/api: Attempted duplicate registration of API: ${type}`
);
diag.error(err.stack || err.message);
return false;
}
if (api.version !== VERSION) {
// All registered APIs must be of the same version exactly
const err = new Error(
'@opentelemetry/api: All API registration versions must match'
);
diag.error(err.stack || err.message);
return false;
}
api[type] = instance;
diag.debug(
`@opentelemetry/api: Registered a global for ${type} v${VERSION}.`
);
return true;
}
export function getGlobal<Type extends keyof OTelGlobalAPI>(
type: Type
): OTelGlobalAPI[Type] | undefined {
const globalVersion = _global[GLOBAL_OPENTELEMETRY_API_KEY]?.version;
if (!globalVersion || !isCompatible(globalVersion)) {
return;
}
return _global[GLOBAL_OPENTELEMETRY_API_KEY]?.[type];
}
export function unregisterGlobal(type: keyof OTelGlobalAPI, diag: DiagLogger) {
diag.debug(
`@opentelemetry/api: Unregistering a global for ${type} v${VERSION}.`
);
const api = _global[GLOBAL_OPENTELEMETRY_API_KEY];
if (api) {
delete api[type];
}
}
type OTelGlobal = {
[GLOBAL_OPENTELEMETRY_API_KEY]?: OTelGlobalAPI;
};
type OTelGlobalAPI = {
version: string;
diag?: DiagLogger;
trace?: TracerProvider;
context?: ContextManager;
propagation?: TextMapPropagator;
};

140
api/src/internal/semver.ts Normal file
View File

@ -0,0 +1,140 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { VERSION } from '../version';
const re = /^(\d+)\.(\d+)\.(\d+)(-(.+))?$/;
/**
* Create a function to test an API version to see if it is compatible with the provided ownVersion.
*
* The returned function has the following semantics:
* - Exact match is always compatible
* - Major versions must match exactly
* - 1.x package cannot use global 2.x package
* - 2.x package cannot use global 1.x package
* - The minor version of the API module requesting access to the global API must be less than or equal to the minor version of this API
* - 1.3 package may use 1.4 global because the later global contains all functions 1.3 expects
* - 1.4 package may NOT use 1.3 global because it may try to call functions which don't exist on 1.3
* - If the major version is 0, the minor version is treated as the major and the patch is treated as the minor
* - Patch and build tag differences are not considered at this time
*
* @param ownVersion version which should be checked against
*/
export function _makeCompatibilityCheck(
ownVersion: string
): (globalVersion: string) => boolean {
const acceptedVersions = new Set<string>([ownVersion]);
const rejectedVersions = new Set<string>();
const myVersionMatch = ownVersion.match(re);
if (!myVersionMatch) {
// we cannot guarantee compatibility so we always return noop
return () => false;
}
const ownVersionParsed = {
major: +myVersionMatch[1],
minor: +myVersionMatch[2],
patch: +myVersionMatch[3],
prerelease: myVersionMatch[4],
};
// if ownVersion has a prerelease tag, versions must match exactly
if (ownVersionParsed.prerelease != null) {
return function isExactmatch(globalVersion: string): boolean {
return globalVersion === ownVersion;
};
}
function _reject(v: string) {
rejectedVersions.add(v);
return false;
}
function _accept(v: string) {
acceptedVersions.add(v);
return true;
}
return function isCompatible(globalVersion: string): boolean {
if (acceptedVersions.has(globalVersion)) {
return true;
}
if (rejectedVersions.has(globalVersion)) {
return false;
}
const globalVersionMatch = globalVersion.match(re);
if (!globalVersionMatch) {
// cannot parse other version
// we cannot guarantee compatibility so we always noop
return _reject(globalVersion);
}
const globalVersionParsed = {
major: +globalVersionMatch[1],
minor: +globalVersionMatch[2],
patch: +globalVersionMatch[3],
prerelease: globalVersionMatch[4],
};
// if globalVersion has a prerelease tag, versions must match exactly
if (globalVersionParsed.prerelease != null) {
return _reject(globalVersion);
}
// major versions must match
if (ownVersionParsed.major !== globalVersionParsed.major) {
return _reject(globalVersion);
}
if (ownVersionParsed.major === 0) {
if (
ownVersionParsed.minor === globalVersionParsed.minor &&
ownVersionParsed.patch <= globalVersionParsed.patch
) {
return _accept(globalVersion);
}
return _reject(globalVersion);
}
if (ownVersionParsed.minor <= globalVersionParsed.minor) {
return _accept(globalVersion);
}
return _reject(globalVersion);
};
}
/**
* Test an API version to see if it is compatible with this API.
*
* - Exact match is always compatible
* - Major versions must match exactly
* - 1.x package cannot use global 2.x package
* - 2.x package cannot use global 1.x package
* - The minor version of the API module requesting access to the global API must be less than or equal to the minor version of this API
* - 1.3 package may use 1.4 global because the later global contains all functions 1.3 expects
* - 1.4 package may NOT use 1.3 global because it may try to call functions which don't exist on 1.3
* - If the major version is 0, the minor version is treated as the major and the patch is treated as the minor
* - Patch and build tag differences are not considered at this time
*
* @param version version of the API requesting an instance of the global API
*/
export const isCompatible = _makeCompatibilityCheck(VERSION);

35
api/src/platform/browser/globalThis.ts Normal file
View File

@ -0,0 +1,35 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// Updates to this file should also be replicated to @opentelemetry/api-metrics and
// @opentelemetry/core too.
/**
* - globalThis (New standard)
* - self (Will return the current window instance for supported browsers)
* - window (fallback for older browser implementations)
* - global (NodeJS implementation)
* - <object> (When all else fails)
*/
/** only globals that common to node and browsers are allowed */
// eslint-disable-next-line node/no-unsupported-features/es-builtins, no-undef
export const _globalThis: typeof globalThis =
typeof globalThis === 'object' ? globalThis :
typeof self === 'object' ? self :
typeof window === 'object' ? window :
typeof global === 'object' ? global :
{} as typeof globalThis;

17
api/src/platform/browser/index.ts Normal file
View File

@ -0,0 +1,17 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export * from './globalThis';

17
api/src/platform/index.ts Normal file
View File

@ -0,0 +1,17 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export * from './node';

19
api/src/platform/node/globalThis.ts Normal file
View File

@ -0,0 +1,19 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** only globals that common to node and browsers are allowed */
// eslint-disable-next-line node/no-unsupported-features/es-builtins
export const _globalThis = typeof globalThis === 'object' ? globalThis : global;

17
api/src/platform/node/index.ts Normal file
View File

@ -0,0 +1,17 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export * from './globalThis';

33
api/src/propagation/NoopTextMapPropagator.ts Normal file
View File

@ -0,0 +1,33 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from '../context/types';
import { TextMapPropagator } from './TextMapPropagator';
/**
* No-op implementations of {@link TextMapPropagator}.
*/
export class NoopTextMapPropagator implements TextMapPropagator {
/** Noop inject function does nothing */
inject(_context: Context, _carrier: unknown): void {}
/** Noop extract function does nothing and returns the input context */
extract(context: Context, _carrier: unknown): Context {
return context;
}
fields(): string[] {
return [];
}
}

137
api/src/propagation/TextMapPropagator.ts Normal file
View File

@ -0,0 +1,137 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from '../context/types';
/**
* Injects `Context` into and extracts it from carriers that travel
* in-band across process boundaries. Encoding is expected to conform to the
* HTTP Header Field semantics. Values are often encoded as RPC/HTTP request
* headers.
*
* The carrier of propagated data on both the client (injector) and server
* (extractor) side is usually an object such as http headers. Propagation is
* usually implemented via library-specific request interceptors, where the
* client-side injects values and the server-side extracts them.
*/
export interface TextMapPropagator<Carrier = any> {
/**
* Injects values from a given `Context` into a carrier.
*
* OpenTelemetry defines a common set of format values (TextMapPropagator),
* and each has an expected `carrier` type.
*
* @param context the Context from which to extract values to transmit over
* the wire.
* @param carrier the carrier of propagation fields, such as http request
* headers.
* @param setter an optional {@link TextMapSetter}. If undefined, values will be
* set by direct object assignment.
*/
inject(
context: Context,
carrier: Carrier,
setter: TextMapSetter<Carrier>
): void;
/**
* Given a `Context` and a carrier, extract context values from a
* carrier and return a new context, created from the old context, with the
* extracted values.
*
* @param context the Context from which to extract values to transmit over
* the wire.
* @param carrier the carrier of propagation fields, such as http request
* headers.
* @param getter an optional {@link TextMapGetter}. If undefined, keys will be all
* own properties, and keys will be accessed by direct object access.
*/
extract(
context: Context,
carrier: Carrier,
getter: TextMapGetter<Carrier>
): Context;
/**
* Return a list of all fields which may be used by the propagator.
*/
fields(): string[];
}
/**
* A setter is specified by the caller to define a specific method
* to set key/value pairs on the carrier within a propagator.
*/
export interface TextMapSetter<Carrier = any> {
/**
* Callback used to set a key/value pair on an object.
*
* Should be called by the propagator each time a key/value pair
* should be set, and should set that key/value pair on the propagator.
*
* @param carrier object or class which carries key/value pairs
* @param key string key to modify
* @param value value to be set to the key on the carrier
*/
set(carrier: Carrier, key: string, value: string): void;
}
/**
* A getter is specified by the caller to define a specific method
* to get the value of a key from a carrier.
*/
export interface TextMapGetter<Carrier = any> {
/**
* Get a list of all keys available on the carrier.
*
* @param carrier
*/
keys(carrier: Carrier): string[];
/**
* Get the value of a specific key from the carrier.
*
* @param carrier
* @param key
*/
get(carrier: Carrier, key: string): undefined | string | string[];
}
export const defaultTextMapGetter: TextMapGetter = {
get(carrier, key) {
if (carrier == null) {
return undefined;
}
return carrier[key];
},
keys(carrier) {
if (carrier == null) {
return [];
}
return Object.keys(carrier);
},
};
export const defaultTextMapSetter: TextMapSetter = {
set(carrier, key, value) {
if (carrier == null) {
return;
}
carrier[key] = value;
},
};

75
api/src/trace/NonRecordingSpan.ts Normal file
View File

@ -0,0 +1,75 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Exception } from '../common/Exception';
import { TimeInput } from '../common/Time';
import { SpanAttributes } from './attributes';
import { INVALID_SPAN_CONTEXT } from './invalid-span-constants';
import { Span } from './span';
import { SpanContext } from './span_context';
import { SpanStatus } from './status';
/**
* The NonRecordingSpan is the default {@link Span} that is used when no Span
* implementation is available. All operations are no-op including context
* propagation.
*/
export class NonRecordingSpan implements Span {
constructor(
private readonly _spanContext: SpanContext = INVALID_SPAN_CONTEXT
) {}
// Returns a SpanContext.
spanContext(): SpanContext {
return this._spanContext;
}
// By default does nothing
setAttribute(_key: string, _value: unknown): this {
return this;
}
// By default does nothing
setAttributes(_attributes: SpanAttributes): this {
return this;
}
// By default does nothing
addEvent(_name: string, _attributes?: SpanAttributes): this {
return this;
}
// By default does nothing
setStatus(_status: SpanStatus): this {
return this;
}
// By default does nothing
updateName(_name: string): this {
return this;
}
// By default does nothing
end(_endTime?: TimeInput): void {}
// isRecording always returns false for NonRecordingSpan.
isRecording(): boolean {
return false;
}
// By default does nothing
recordException(_exception: Exception, _time?: TimeInput): void {}
}

105
api/src/trace/NoopTracer.ts Normal file
View File

@ -0,0 +1,105 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ContextAPI } from '../api/context';
import { Context } from '../context/types';
import { getSpanContext, setSpan } from '../trace/context-utils';
import { NonRecordingSpan } from './NonRecordingSpan';
import { Span } from './span';
import { isSpanContextValid } from './spancontext-utils';
import { SpanOptions } from './SpanOptions';
import { SpanContext } from './span_context';
import { Tracer } from './tracer';
const context = ContextAPI.getInstance();
/**
* No-op implementations of {@link Tracer}.
*/
export class NoopTracer implements Tracer {
// startSpan starts a noop span.
startSpan(name: string, options?: SpanOptions, context?: Context): Span {
const root = Boolean(options?.root);
if (root) {
return new NonRecordingSpan();
}
const parentFromContext = context && getSpanContext(context);
if (
isSpanContext(parentFromContext) &&
isSpanContextValid(parentFromContext)
) {
return new NonRecordingSpan(parentFromContext);
} else {
return new NonRecordingSpan();
}
}
startActiveSpan<F extends (span: Span) => ReturnType<F>>(
name: string,
fn: F
): ReturnType<F>;
startActiveSpan<F extends (span: Span) => ReturnType<F>>(
name: string,
opts: SpanOptions | undefined,
fn: F
): ReturnType<F>;
startActiveSpan<F extends (span: Span) => ReturnType<F>>(
name: string,
opts: SpanOptions | undefined,
ctx: Context | undefined,
fn: F
): ReturnType<F>;
startActiveSpan<F extends (span: Span) => ReturnType<F>>(
name: string,
arg2?: F | SpanOptions,
arg3?: F | Context,
arg4?: F
): ReturnType<F> | undefined {
let opts: SpanOptions | undefined;
let ctx: Context | undefined;
let fn: F;
if (arguments.length < 2) {
return;
} else if (arguments.length === 2) {
fn = arg2 as F;
} else if (arguments.length === 3) {
opts = arg2 as SpanOptions | undefined;
fn = arg3 as F;
} else {
opts = arg2 as SpanOptions | undefined;
ctx = arg3 as Context | undefined;
fn = arg4 as F;
}
const parentContext = ctx ?? context.active();
const span = this.startSpan(name, opts, parentContext);
const contextWithSpanSet = setSpan(parentContext, span);
return context.with(contextWithSpanSet, fn, undefined, span);
}
}
function isSpanContext(spanContext: any): spanContext is SpanContext {
return (
typeof spanContext === 'object' &&
typeof spanContext['spanId'] === 'string' &&
typeof spanContext['traceId'] === 'string' &&
typeof spanContext['traceFlags'] === 'number'
);
}

36
api/src/trace/NoopTracerProvider.ts Normal file
View File

@ -0,0 +1,36 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { NoopTracer } from './NoopTracer';
import { Tracer } from './tracer';
import { TracerOptions } from './tracer_options';
import { TracerProvider } from './tracer_provider';
/**
* An implementation of the {@link TracerProvider} which returns an impotent
* Tracer for all calls to `getTracer`.
*
* All operations are no-op.
*/
export class NoopTracerProvider implements TracerProvider {
getTracer(
_name?: string,
_version?: string,
_options?: TracerOptions
): Tracer {
return new NoopTracer();
}
}

76
api/src/trace/ProxyTracer.ts Normal file
View File

@ -0,0 +1,76 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from '../context/types';
import { NoopTracer } from './NoopTracer';
import { Span } from './span';
import { SpanOptions } from './SpanOptions';
import { Tracer } from './tracer';
import { TracerOptions } from './tracer_options';
const NOOP_TRACER = new NoopTracer();
/**
* Proxy tracer provided by the proxy tracer provider
*/
export class ProxyTracer implements Tracer {
// When a real implementation is provided, this will be it
private _delegate?: Tracer;
constructor(
private _provider: TracerDelegator,
public readonly name: string,
public readonly version?: string,
public readonly options?: TracerOptions
) {}
startSpan(name: string, options?: SpanOptions, context?: Context): Span {
return this._getTracer().startSpan(name, options, context);
}
startActiveSpan<F extends (span: Span) => unknown>(
_name: string,
_options: F | SpanOptions,
_context?: F | Context,
_fn?: F
): ReturnType<F> {
const tracer = this._getTracer();
return Reflect.apply(tracer.startActiveSpan, tracer, arguments);
}
/**
* Try to get a tracer from the proxy tracer provider.
* If the proxy tracer provider has no delegate, return a noop tracer.
*/
private _getTracer() {
if (this._delegate) {
return this._delegate;
}
const tracer = this._provider.getDelegateTracer(this.name, this.version, this.options);
if (!tracer) {
return NOOP_TRACER;
}
this._delegate = tracer;
return this._delegate;
}
}
export interface TracerDelegator {
getDelegateTracer(name: string, version?: string, options?: TracerOptions): Tracer | undefined;
}

64
api/src/trace/ProxyTracerProvider.ts Normal file
View File

@ -0,0 +1,64 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Tracer } from './tracer';
import { TracerProvider } from './tracer_provider';
import { ProxyTracer } from './ProxyTracer';
import { NoopTracerProvider } from './NoopTracerProvider';
import { TracerOptions } from './tracer_options';
const NOOP_TRACER_PROVIDER = new NoopTracerProvider();
/**
* Tracer provider which provides {@link ProxyTracer}s.
*
* Before a delegate is set, tracers provided are NoOp.
* When a delegate is set, traces are provided from the delegate.
* When a delegate is set after tracers have already been provided,
* all tracers already provided will use the provided delegate implementation.
*/
export class ProxyTracerProvider implements TracerProvider {
private _delegate?: TracerProvider;
/**
* Get a {@link ProxyTracer}
*/
getTracer(name: string, version?: string, options?: TracerOptions): Tracer {
return (
this.getDelegateTracer(name, version, options) ??
new ProxyTracer(this, name, version, options)
);
}
getDelegate(): TracerProvider {
return this._delegate ?? NOOP_TRACER_PROVIDER;
}
/**
* Set the delegate tracer provider
*/
setDelegate(delegate: TracerProvider) {
this._delegate = delegate;
}
getDelegateTracer(
name: string,
version?: string,
options?: TracerOptions
): Tracer | undefined {
return this._delegate?.getTracer(name, version, options);
}
}

55
api/src/trace/Sampler.ts Normal file
View File

@ -0,0 +1,55 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from '../context/types';
import { SpanAttributes } from './attributes';
import { Link } from './link';
import { SamplingResult } from './SamplingResult';
import { SpanKind } from './span_kind';
/**
* @deprecated use the one declared in @opentelemetry/sdk-trace-base instead.
* This interface represent a sampler. Sampling is a mechanism to control the
* noise and overhead introduced by OpenTelemetry by reducing the number of
* samples of traces collected and sent to the backend.
*/
export interface Sampler {
/**
* Checks whether span needs to be created and tracked.
*
* @param context Parent Context which may contain a span.
* @param traceId of the span to be created. It can be different from the
* traceId in the {@link SpanContext}. Typically in situations when the
* span to be created starts a new trace.
* @param spanName of the span to be created.
* @param spanKind of the span to be created.
* @param attributes Initial set of SpanAttributes for the Span being constructed.
* @param links Collection of links that will be associated with the Span to
* be created. Typically useful for batch operations.
* @returns a {@link SamplingResult}.
*/
shouldSample(
context: Context,
traceId: string,
spanName: string,
spanKind: SpanKind,
attributes: SpanAttributes,
links: Link[]
): SamplingResult;
/** Returns the sampler name or short description with the configuration. */
toString(): string;
}

58
api/src/trace/SamplingResult.ts Normal file
View File

@ -0,0 +1,58 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { SpanAttributes } from './attributes';
/**
* @deprecated use the one declared in @opentelemetry/sdk-trace-base instead.
* A sampling decision that determines how a {@link Span} will be recorded
* and collected.
*/
export enum SamplingDecision {
/**
* `Span.isRecording() === false`, span will not be recorded and all events
* and attributes will be dropped.
*/
NOT_RECORD,
/**
* `Span.isRecording() === true`, but `Sampled` flag in {@link TraceFlags}
* MUST NOT be set.
*/
RECORD,
/**
* `Span.isRecording() === true` AND `Sampled` flag in {@link TraceFlags}
* MUST be set.
*/
RECORD_AND_SAMPLED,
}
/**
* @deprecated use the one declared in @opentelemetry/sdk-trace-base instead.
* A sampling result contains a decision for a {@link Span} and additional
* attributes the sampler would like to added to the Span.
*/
export interface SamplingResult {
/**
* A sampling decision, refer to {@link SamplingDecision} for details.
*/
decision: SamplingDecision;
/**
* The list of attributes returned by SamplingResult MUST be immutable.
* Caller may call {@link Sampler}.shouldSample any number of times and
* can safely cache the returned value.
*/
attributes?: Readonly<SpanAttributes>;
}

43
api/src/trace/SpanOptions.ts Normal file
View File

@ -0,0 +1,43 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { TimeInput } from '../common/Time';
import { SpanAttributes } from './attributes';
import { Link } from './link';
import { SpanKind } from './span_kind';
/**
* Options needed for span creation
*/
export interface SpanOptions {
/**
* The SpanKind of a span
* @default {@link SpanKind.INTERNAL}
*/
kind?: SpanKind;
/** A span's attributes */
attributes?: SpanAttributes;
/** {@link Link}s span to other spans */
links?: Link[];
/** A manually specified start time for the created `Span` object. */
startTime?: TimeInput;
/** The new span should be a root span. (Ignore parent from context). */
root?: boolean;
}

27
api/src/trace/attributes.ts Normal file
View File

@ -0,0 +1,27 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Attributes, AttributeValue } from '../common/Attributes';
/**
* @deprecated please use {@link Attributes}
*/
export type SpanAttributes = Attributes;
/**
* @deprecated please use {@link AttributeValue}
*/
export type SpanAttributeValue = AttributeValue;

85
api/src/trace/context-utils.ts Normal file
View File

@ -0,0 +1,85 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { createContextKey } from '../context/context';
import { Context } from '../context/types';
import { Span } from './span';
import { SpanContext } from './span_context';
import { NonRecordingSpan } from './NonRecordingSpan';
import { ContextAPI } from '../api/context';
/**
* span key
*/
const SPAN_KEY = createContextKey('OpenTelemetry Context Key SPAN');
/**
* Return the span if one exists
*
* @param context context to get span from
*/
export function getSpan(context: Context): Span | undefined {
return (context.getValue(SPAN_KEY) as Span) || undefined;
}
/**
* Gets the span from the current context, if one exists.
*/
export function getActiveSpan(): Span | undefined {
return getSpan(ContextAPI.getInstance().active());
}
/**
* Set the span on a context
*
* @param context context to use as parent
* @param span span to set active
*/
export function setSpan(context: Context, span: Span): Context {
return context.setValue(SPAN_KEY, span);
}
/**
* Remove current span stored in the context
*
* @param context context to delete span from
*/
export function deleteSpan(context: Context): Context {
return context.deleteValue(SPAN_KEY);
}
/**
* Wrap span context in a NoopSpan and set as span in a new
* context
*
* @param context context to set active span on
* @param spanContext span context to be wrapped
*/
export function setSpanContext(
context: Context,
spanContext: SpanContext
): Context {
return setSpan(context, new NonRecordingSpan(spanContext));
}
/**
* Get the span context of the span if it exists.
*
* @param context context to get values from
*/
export function getSpanContext(context: Context): SpanContext | undefined {
return getSpan(context)?.spanContext();
}

110
api/src/trace/internal/tracestate-impl.ts Normal file
View File

@ -0,0 +1,110 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { TraceState } from '../trace_state';
import { validateKey, validateValue } from './tracestate-validators';
const MAX_TRACE_STATE_ITEMS = 32;
const MAX_TRACE_STATE_LEN = 512;
const LIST_MEMBERS_SEPARATOR = ',';
const LIST_MEMBER_KEY_VALUE_SPLITTER = '=';
/**
* TraceState must be a class and not a simple object type because of the spec
* requirement (https://www.w3.org/TR/trace-context/#tracestate-field).
*
* Here is the list of allowed mutations:
* - New key-value pair should be added into the beginning of the list
* - The value of any key can be updated. Modified keys MUST be moved to the
* beginning of the list.
*/
export class TraceStateImpl implements TraceState {
private _internalState: Map<string, string> = new Map();
constructor(rawTraceState?: string) {
if (rawTraceState) this._parse(rawTraceState);
}
set(key: string, value: string): TraceStateImpl {
// TODO: Benchmark the different approaches(map vs list) and
// use the faster one.
const traceState = this._clone();
if (traceState._internalState.has(key)) {
traceState._internalState.delete(key);
}
traceState._internalState.set(key, value);
return traceState;
}
unset(key: string): TraceStateImpl {
const traceState = this._clone();
traceState._internalState.delete(key);
return traceState;
}
get(key: string): string | undefined {
return this._internalState.get(key);
}
serialize(): string {
return this._keys()
.reduce((agg: string[], key) => {
agg.push(key + LIST_MEMBER_KEY_VALUE_SPLITTER + this.get(key));
return agg;
}, [])
.join(LIST_MEMBERS_SEPARATOR);
}
private _parse(rawTraceState: string) {
if (rawTraceState.length > MAX_TRACE_STATE_LEN) return;
this._internalState = rawTraceState
.split(LIST_MEMBERS_SEPARATOR)
.reverse() // Store in reverse so new keys (.set(...)) will be placed at the beginning
.reduce((agg: Map<string, string>, part: string) => {
const listMember = part.trim(); // Optional Whitespace (OWS) handling
const i = listMember.indexOf(LIST_MEMBER_KEY_VALUE_SPLITTER);
if (i !== -1) {
const key = listMember.slice(0, i);
const value = listMember.slice(i + 1, part.length);
if (validateKey(key) && validateValue(value)) {
agg.set(key, value);
} else {
// TODO: Consider to add warning log
}
}
return agg;
}, new Map());
// Because of the reverse() requirement, trunc must be done after map is created
if (this._internalState.size > MAX_TRACE_STATE_ITEMS) {
this._internalState = new Map(
Array.from(this._internalState.entries())
.reverse() // Use reverse same as original tracestate parse chain
.slice(0, MAX_TRACE_STATE_ITEMS)
);
}
}
private _keys(): string[] {
return Array.from(this._internalState.keys()).reverse();
}
private _clone(): TraceStateImpl {
const traceState = new TraceStateImpl();
traceState._internalState = new Map(this._internalState);
return traceState;
}
}

45
api/src/trace/internal/tracestate-validators.ts Normal file
View File

@ -0,0 +1,45 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
const VALID_KEY_CHAR_RANGE = '[_0-9a-z-*/]';
const VALID_KEY = `[a-z]${VALID_KEY_CHAR_RANGE}{0,255}`;
const VALID_VENDOR_KEY = `[a-z0-9]${VALID_KEY_CHAR_RANGE}{0,240}@[a-z]${VALID_KEY_CHAR_RANGE}{0,13}`;
const VALID_KEY_REGEX = new RegExp(`^(?:${VALID_KEY}|${VALID_VENDOR_KEY})$`);
const VALID_VALUE_BASE_REGEX = /^[ -~]{0,255}[!-~]$/;
const INVALID_VALUE_COMMA_EQUAL_REGEX = /,|=/;
/**
* Key is opaque string up to 256 characters printable. It MUST begin with a
* lowercase letter, and can only contain lowercase letters a-z, digits 0-9,
* underscores _, dashes -, asterisks *, and forward slashes /.
* For multi-tenant vendor scenarios, an at sign (@) can be used to prefix the
* vendor name. Vendors SHOULD set the tenant ID at the beginning of the key.
* see https://www.w3.org/TR/trace-context/#key
*/
export function validateKey(key: string): boolean {
return VALID_KEY_REGEX.test(key);
}
/**
* Value is opaque string up to 256 characters printable ASCII RFC0020
* characters (i.e., the range 0x20 to 0x7E) except comma , and =.
*/
export function validateValue(value: string): boolean {
return (
VALID_VALUE_BASE_REGEX.test(value) &&
!INVALID_VALUE_COMMA_EQUAL_REGEX.test(value)
);
}

23
api/src/trace/internal/utils.ts Normal file
View File

@ -0,0 +1,23 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { TraceState } from '../trace_state';
import { TraceStateImpl } from './tracestate-impl';
export function createTraceState(rawTraceState?: string): TraceState {
return new TraceStateImpl(rawTraceState);
}

26
api/src/trace/invalid-span-constants.ts Normal file
View File

@ -0,0 +1,26 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { SpanContext } from './span_context';
import { TraceFlags } from './trace_flags';
export const INVALID_SPANID = '0000000000000000';
export const INVALID_TRACEID = '00000000000000000000000000000000';
export const INVALID_SPAN_CONTEXT: SpanContext = {
traceId: INVALID_TRACEID,
spanId: INVALID_SPANID,
traceFlags: TraceFlags.NONE,
};

40
api/src/trace/link.ts Normal file
View File

@ -0,0 +1,40 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { SpanAttributes } from './attributes';
import { SpanContext } from './span_context';
/**
* A pointer from the current {@link Span} to another span in the same trace or
* in a different trace.
* Few examples of Link usage.
* 1. Batch Processing: A batch of elements may contain elements associated
* with one or more traces/spans. Since there can only be one parent
* SpanContext, Link is used to keep reference to SpanContext of all
* elements in the batch.
* 2. Public Endpoint: A SpanContext in incoming client request on a public
* endpoint is untrusted from service provider perspective. In such case it
* is advisable to start a new trace with appropriate sampling decision.
* However, it is desirable to associate incoming SpanContext to new trace
* initiated on service provider side so two traces (from Client and from
* Service Provider) can be correlated.
*/
export interface Link {
/** The {@link SpanContext} of a linked span. */
context: SpanContext;
/** A set of {@link SpanAttributes} on the link. */
attributes?: SpanAttributes;
}

129
api/src/trace/span.ts Normal file
View File

@ -0,0 +1,129 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Exception } from '../common/Exception';
import { TimeInput } from '../common/Time';
import { SpanAttributes, SpanAttributeValue } from './attributes';
import { SpanContext } from './span_context';
import { SpanStatus } from './status';
/**
* An interface that represents a span. A span represents a single operation
* within a trace. Examples of span might include remote procedure calls or a
* in-process function calls to sub-components. A Trace has a single, top-level
* "root" Span that in turn may have zero or more child Spans, which in turn
* may have children.
*
* Spans are created by the {@link Tracer.startSpan} method.
*/
export interface Span {
/**
* Returns the {@link SpanContext} object associated with this Span.
*
* Get an immutable, serializable identifier for this span that can be used
* to create new child spans. Returned SpanContext is usable even after the
* span ends.
*
* @returns the SpanContext object associated with this Span.
*/
spanContext(): SpanContext;
/**
* Sets an attribute to the span.
*
* Sets a single Attribute with the key and value passed as arguments.
*
* @param key the key for this attribute.
* @param value the value for this attribute. Setting a value null or
* undefined is invalid and will result in undefined behavior.
*/
setAttribute(key: string, value: SpanAttributeValue): this;
/**
* Sets attributes to the span.
*
* @param attributes the attributes that will be added.
* null or undefined attribute values
* are invalid and will result in undefined behavior.
*/
setAttributes(attributes: SpanAttributes): this;
/**
* Adds an event to the Span.
*
* @param name the name of the event.
* @param [attributesOrStartTime] the attributes that will be added; these are
* associated with this event. Can be also a start time
* if type is {@type TimeInput} and 3rd param is undefined
* @param [startTime] start time of the event.
*/
addEvent(
name: string,
attributesOrStartTime?: SpanAttributes | TimeInput,
startTime?: TimeInput
): this;
/**
* Sets a status to the span. If used, this will override the default Span
* status. Default is {@link SpanStatusCode.UNSET}. SetStatus overrides the value
* of previous calls to SetStatus on the Span.
*
* @param status the SpanStatus to set.
*/
setStatus(status: SpanStatus): this;
/**
* Updates the Span name.
*
* This will override the name provided via {@link Tracer.startSpan}.
*
* Upon this update, any sampling behavior based on Span name will depend on
* the implementation.
*
* @param name the Span name.
*/
updateName(name: string): this;
/**
* Marks the end of Span execution.
*
* Call to End of a Span MUST not have any effects on child spans. Those may
* still be running and can be ended later.
*
* Do not return `this`. The Span generally should not be used after it
* is ended so chaining is not desired in this context.
*
* @param [endTime] the time to set as Span's end time. If not provided,
* use the current time as the span's end time.
*/
end(endTime?: TimeInput): void;
/**
* Returns the flag whether this span will be recorded.
*
* @returns true if this Span is active and recording information like events
* with the `AddEvent` operation and attributes using `setAttributes`.
*/
isRecording(): boolean;
/**
* Sets exception as a span event
* @param exception the exception the only accepted values are string or Error
* @param [time] the time to set as Span's event time. If not provided,
* use the current time.
*/
recordException(exception: Exception, time?: TimeInput): void;
}

69
api/src/trace/span_context.ts Normal file
View File

@ -0,0 +1,69 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { TraceState } from './trace_state';
/**
* A SpanContext represents the portion of a {@link Span} which must be
* serialized and propagated along side of a {@link Baggage}.
*/
export interface SpanContext {
/**
* The ID of the trace that this span belongs to. It is worldwide unique
* with practically sufficient probability by being made as 16 randomly
* generated bytes, encoded as a 32 lowercase hex characters corresponding to
* 128 bits.
*/
traceId: string;
/**
* The ID of the Span. It is globally unique with practically sufficient
* probability by being made as 8 randomly generated bytes, encoded as a 16
* lowercase hex characters corresponding to 64 bits.
*/
spanId: string;
/**
* Only true if the SpanContext was propagated from a remote parent.
*/
isRemote?: boolean;
/**
* Trace flags to propagate.
*
* It is represented as 1 byte (bitmap). Bit to represent whether trace is
* sampled or not. When set, the least significant bit documents that the
* caller may have recorded trace data. A caller who does not record trace
* data out-of-band leaves this flag unset.
*
* see {@link TraceFlags} for valid flag values.
*/
traceFlags: number;
/**
* Tracing-system-specific info to propagate.
*
* The tracestate field value is a `list` as defined below. The `list` is a
* series of `list-members` separated by commas `,`, and a list-member is a
* key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
* surrounding `list-members` are ignored. There can be a maximum of 32
* `list-members` in a `list`.
* More Info: https://www.w3.org/TR/trace-context/#tracestate-field
*
* Examples:
* Single tracing system (generic format):
* tracestate: rojo=00f067aa0ba902b7
* Multiple tracing systems (with different formatting):
* tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
*/
traceState?: TraceState;
}

45
api/src/trace/span_kind.ts Normal file
View File

@ -0,0 +1,45 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export enum SpanKind {
/** Default value. Indicates that the span is used internally. */
INTERNAL = 0,
/**
* Indicates that the span covers server-side handling of an RPC or other
* remote request.
*/
SERVER = 1,
/**
* Indicates that the span covers the client-side wrapper around an RPC or
* other remote request.
*/
CLIENT = 2,
/**
* Indicates that the span describes producer sending a message to a
* broker. Unlike client and server, there is no direct critical path latency
* relationship between producer and consumer spans.
*/
PRODUCER = 3,
/**
* Indicates that the span describes consumer receiving a message from a
* broker. Unlike client and server, there is no direct critical path latency
* relationship between producer and consumer spans.
*/
CONSUMER = 4,
}

50
api/src/trace/spancontext-utils.ts Normal file
View File

@ -0,0 +1,50 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { INVALID_SPANID, INVALID_TRACEID } from './invalid-span-constants';
import { NonRecordingSpan } from './NonRecordingSpan';
import { Span } from './span';
import { SpanContext } from './span_context';
const VALID_TRACEID_REGEX = /^([0-9a-f]{32})$/i;
const VALID_SPANID_REGEX = /^[0-9a-f]{16}$/i;
export function isValidTraceId(traceId: string): boolean {
return VALID_TRACEID_REGEX.test(traceId) && traceId !== INVALID_TRACEID;
}
export function isValidSpanId(spanId: string): boolean {
return VALID_SPANID_REGEX.test(spanId) && spanId !== INVALID_SPANID;
}
/**
* Returns true if this {@link SpanContext} is valid.
* @return true if this {@link SpanContext} is valid.
*/
export function isSpanContextValid(spanContext: SpanContext): boolean {
return (
isValidTraceId(spanContext.traceId) && isValidSpanId(spanContext.spanId)
);
}
/**
* Wrap the given {@link SpanContext} in a new non-recording {@link Span}
*
* @param spanContext span context to be wrapped
* @returns a new non-recording {@link Span} with the provided context
*/
export function wrapSpanContext(spanContext: SpanContext): Span {
return new NonRecordingSpan(spanContext);
}

40
api/src/trace/status.ts Normal file
View File

@ -0,0 +1,40 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export interface SpanStatus {
/** The status code of this message. */
code: SpanStatusCode;
/** A developer-facing error message. */
message?: string;
}
/**
* An enumeration of status codes.
*/
export enum SpanStatusCode {
/**
* The default status.
*/
UNSET = 0,
/**
* The operation has been validated by an Application developer or
* Operator to have completed successfully.
*/
OK = 1,
/**
* The operation contains an error.
*/
ERROR = 2,
}

21
api/src/trace/trace_flags.ts Normal file
View File

@ -0,0 +1,21 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export enum TraceFlags {
/** Represents no flag set. */
NONE = 0x0,
/** Bit to represent whether trace is sampled in trace flags. */
SAMPLED = 0x1 << 0,
}

59
api/src/trace/trace_state.ts Normal file
View File

@ -0,0 +1,59 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export interface TraceState {
/**
* Create a new TraceState which inherits from this TraceState and has the
* given key set.
* The new entry will always be added in the front of the list of states.
*
* @param key key of the TraceState entry.
* @param value value of the TraceState entry.
*/
set(key: string, value: string): TraceState;
/**
* Return a new TraceState which inherits from this TraceState but does not
* contain the given key.
*
* @param key the key for the TraceState entry to be removed.
*/
unset(key: string): TraceState;
/**
* Returns the value to which the specified key is mapped, or `undefined` if
* this map contains no mapping for the key.
*
* @param key with which the specified value is to be associated.
* @returns the value to which the specified key is mapped, or `undefined` if
* this map contains no mapping for the key.
*/
get(key: string): string | undefined;
// TODO: Consider to add support for merging an object as well by also
// accepting a single internalTraceState argument similar to the constructor.
/**
* Serializes the TraceState to a `list` as defined below. The `list` is a
* series of `list-members` separated by commas `,`, and a list-member is a
* key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
* surrounding `list-members` are ignored. There can be a maximum of 32
* `list-members` in a `list`.
*
* @returns the serialized string.
*/
serialize(): string;
}

100
api/src/trace/tracer.ts Normal file
View File

@ -0,0 +1,100 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Context } from '../context/types';
import { Span } from './span';
import { SpanOptions } from './SpanOptions';
/**
* Tracer provides an interface for creating {@link Span}s.
*/
export interface Tracer {
/**
* Starts a new {@link Span}. Start the span without setting it on context.
*
* This method do NOT modify the current Context.
*
* @param name The name of the span
* @param [options] SpanOptions used for span creation
* @param [context] Context to use to extract parent
* @returns Span The newly created span
* @example
* const span = tracer.startSpan('op');
* span.setAttribute('key', 'value');
* span.end();
*/
startSpan(name: string, options?: SpanOptions, context?: Context): Span;
/**
* Starts a new {@link Span} and calls the given function passing it the
* created span as first argument.
* Additionally the new span gets set in context and this context is activated
* for the duration of the function call.
*
* @param name The name of the span
* @param [options] SpanOptions used for span creation
* @param [context] Context to use to extract parent
* @param fn function called in the context of the span and receives the newly created span as an argument
* @returns return value of fn
* @example
* const something = tracer.startActiveSpan('op', span => {
* try {
* do some work
* span.setStatus({code: SpanStatusCode.OK});
* return something;
* } catch (err) {
* span.setStatus({
* code: SpanStatusCode.ERROR,
* message: err.message,
* });
* throw err;
* } finally {
* span.end();
* }
* });
*
* @example
* const span = tracer.startActiveSpan('op', span => {
* try {
* do some work
* return span;
* } catch (err) {
* span.setStatus({
* code: SpanStatusCode.ERROR,
* message: err.message,
* });
* throw err;
* }
* });
* do some more work
* span.end();
*/
startActiveSpan<F extends (span: Span) => unknown>(
name: string,
fn: F
): ReturnType<F>;
startActiveSpan<F extends (span: Span) => unknown>(
name: string,
options: SpanOptions,
fn: F
): ReturnType<F>;
startActiveSpan<F extends (span: Span) => unknown>(
name: string,
options: SpanOptions,
context: Context,
fn: F
): ReturnType<F>;
}

25
api/src/trace/tracer_options.ts Normal file
View File

@ -0,0 +1,25 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* An interface describes additional metadata of a tracer.
*/
export interface TracerOptions {
/**
* The schemaUrl of the tracer or instrumentation library
*/
schemaUrl?: string;
}

37
api/src/trace/tracer_provider.ts Normal file
View File

@ -0,0 +1,37 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { Tracer } from './tracer';
import { TracerOptions } from './tracer_options';
/**
* A registry for creating named {@link Tracer}s.
*/
export interface TracerProvider {
/**
* Returns a Tracer, creating one if one with the given name and version is
* not already created.
*
* This function may return different Tracer types (e.g.
* {@link NoopTracerProvider} vs. a functional tracer).
*
* @param name The name of the tracer or instrumentation library.
* @param version The version of the tracer or instrumentation library.
* @param options The options of the tracer or instrumentation library.
* @returns Tracer A Tracer with the given name and version
*/
getTracer(name: string, version?: string, options?: TracerOptions): Tracer;
}

253
api/test/api/api.test.ts Normal file
View File

@ -0,0 +1,253 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import api, {
context,
Context,
defaultTextMapGetter,
defaultTextMapSetter,
diag,
propagation,
ROOT_CONTEXT,
Span,
SpanOptions,
TextMapGetter,
TextMapPropagator,
TextMapSetter,
trace,
TraceFlags,
} from '../../src';
import { DiagAPI } from '../../src/api/diag';
import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan';
import { NoopTracer } from '../../src/trace/NoopTracer';
import { NoopTracerProvider } from '../../src/trace/NoopTracerProvider';
// DiagLogger implementation
const diagLoggerFunctions = [
'verbose',
'debug',
'info',
'warn',
'error',
] as const;
describe('API', () => {
it('should expose a tracer provider via getTracerProvider', () => {
const tracer = api.trace.getTracerProvider();
assert.ok(tracer);
assert.strictEqual(typeof tracer, 'object');
});
it('getActiveSpan should get the current span', () => {
const span = new NonRecordingSpan();
const ctx = trace.setSpan(ROOT_CONTEXT, span);
context.setGlobalContextManager({ active: () => ctx, disable: () => {} } as any);
const active = trace.getActiveSpan();
assert.strictEqual(active, span);
context.disable();
});
describe('Context', () => {
it('with should forward this, arguments and return value', () => {
function fnWithThis(this: string, a: string, b: number): string {
assert.strictEqual(this, 'that');
assert.strictEqual(arguments.length, 2);
assert.strictEqual(a, 'one');
assert.strictEqual(b, 2);
return 'done';
}
const res = context.with(ROOT_CONTEXT, fnWithThis, 'that', 'one', 2);
assert.strictEqual(res, 'done');
assert.strictEqual(
context.with(ROOT_CONTEXT, () => 3.14),
3.14
);
});
});
describe('GlobalTracerProvider', () => {
const spanContext = {
traceId: 'd4cda95b652f4a1592b449d5929fda1b',
spanId: '6e0c63257de34c92',
traceFlags: TraceFlags.NONE,
};
const dummySpan = new NonRecordingSpan(spanContext);
beforeEach(() => {
context.disable();
trace.disable();
propagation.disable();
});
it('should use the global tracer provider', () => {
api.trace.setGlobalTracerProvider(new TestTracerProvider());
const tracer = api.trace.getTracerProvider().getTracer('name');
const span = tracer.startSpan('test');
assert.deepStrictEqual(span, dummySpan);
});
it('should set delegate only on success', () => {
assert.strictEqual(
api.trace.setGlobalTracerProvider(new TestTracerProvider()),
true
);
assert.strictEqual(
api.trace.setGlobalTracerProvider(new NoopTracerProvider()),
false
);
assert.ok(api.trace.getTracer('name') instanceof TestTracer);
});
class TestTracer extends NoopTracer {
override startSpan(name: string, options?: SpanOptions): Span {
return dummySpan;
}
}
class TestTracerProvider extends NoopTracerProvider {
override getTracer(_name: string, version?: string) {
return new TestTracer();
}
}
describe('should use the global propagation', () => {
const testKey = Symbol('kTestKey');
interface Carrier {
context?: Context;
setter?: TextMapSetter;
}
class TestTextMapPropagation implements TextMapPropagator<Carrier> {
inject(
context: Context,
carrier: Carrier,
setter: TextMapSetter
): void {
carrier.context = context;
carrier.setter = setter;
}
extract(
context: Context,
carrier: Carrier,
getter: TextMapGetter
): Context {
return context.setValue(testKey, {
context,
carrier,
getter,
});
}
fields(): string[] {
return ['TestField'];
}
}
it('inject', () => {
api.propagation.setGlobalPropagator(new TestTextMapPropagation());
const context = ROOT_CONTEXT.setValue(testKey, 15);
const carrier: Carrier = {};
api.propagation.inject(context, carrier);
assert.strictEqual(carrier.context, context);
assert.strictEqual(carrier.setter, defaultTextMapSetter);
const setter: TextMapSetter = {
set: () => {},
};
api.propagation.inject(context, carrier, setter);
assert.strictEqual(carrier.context, context);
assert.strictEqual(carrier.setter, setter);
});
it('extract', () => {
api.propagation.setGlobalPropagator(new TestTextMapPropagation());
const carrier: Carrier = {};
let context = api.propagation.extract(ROOT_CONTEXT, carrier);
let data: any = context.getValue(testKey);
assert.ok(data != null);
assert.strictEqual(data.context, ROOT_CONTEXT);
assert.strictEqual(data.carrier, carrier);
assert.strictEqual(data.getter, defaultTextMapGetter);
const getter: TextMapGetter = {
keys: () => [],
get: () => undefined,
};
context = api.propagation.extract(ROOT_CONTEXT, carrier, getter);
data = context.getValue(testKey);
assert.ok(data != null);
assert.strictEqual(data.context, ROOT_CONTEXT);
assert.strictEqual(data.carrier, carrier);
assert.strictEqual(data.getter, getter);
});
it('fields', () => {
api.propagation.setGlobalPropagator(new TestTextMapPropagation());
const fields = api.propagation.fields();
assert.deepStrictEqual(fields, ['TestField']);
});
});
});
describe('Global diag', () => {
it('initialization', () => {
const inst = DiagAPI.instance();
assert.deepStrictEqual(diag, inst);
});
diagLoggerFunctions.forEach(fName => {
it(`no argument logger ${fName} message doesn't throw`, () => {
//@ts-expect-error an undefined logger is not allowed
diag.setLogger();
assert.doesNotThrow(() => {
diag[fName](`${fName} message`);
});
});
it(`null logger ${fName} message doesn't throw`, () => {
diag.setLogger(null as any);
assert.doesNotThrow(() => {
diag[fName](`${fName} message`);
});
});
it(`undefined logger ${fName} message doesn't throw`, () => {
diag.setLogger(undefined as any);
assert.doesNotThrow(() => {
diag[fName](`${fName} message`);
});
});
it(`empty logger ${fName} message doesn't throw`, () => {
diag.setLogger({} as any);
assert.doesNotThrow(() => {
diag[fName](`${fName} message`);
});
});
});
});
});

161
api/test/baggage/Baggage.test.ts Normal file
View File

@ -0,0 +1,161 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import {
ROOT_CONTEXT,
propagation,
baggageEntryMetadataFromString,
} from '../../src';
describe('Baggage', () => {
describe('create', () => {
it('should create an empty bag', () => {
const bag = propagation.createBaggage();
assert.deepStrictEqual(bag.getAllEntries(), []);
});
it('should create a bag with entries', () => {
const meta = baggageEntryMetadataFromString('opaque string');
const bag = propagation.createBaggage({
key1: { value: 'value1' },
key2: { value: 'value2', metadata: meta },
});
assert.deepStrictEqual(bag.getAllEntries(), [
['key1', { value: 'value1' }],
['key2', { value: 'value2', metadata: meta }],
]);
});
});
describe('get', () => {
it('should not allow modification of returned entries', () => {
const bag = propagation
.createBaggage()
.setEntry('key', { value: 'value' });
const entry = bag.getEntry('key');
assert.ok(entry);
entry.value = 'mutated';
assert.strictEqual(bag.getEntry('key')?.value, 'value');
});
});
describe('set', () => {
it('should create a new bag when an entry is added', () => {
const bag = propagation.createBaggage();
const bag2 = bag.setEntry('key', { value: 'value' });
assert.notStrictEqual(bag, bag2);
assert.deepStrictEqual(bag.getAllEntries(), []);
assert.deepStrictEqual(bag2.getAllEntries(), [
['key', { value: 'value' }],
]);
});
});
describe('remove', () => {
it('should create a new bag when an entry is removed', () => {
const bag = propagation.createBaggage({
key: { value: 'value' },
});
const bag2 = bag.removeEntry('key');
assert.deepStrictEqual(bag.getAllEntries(), [
['key', { value: 'value' }],
]);
assert.deepStrictEqual(bag2.getAllEntries(), []);
});
it('should create an empty bag multiple keys are removed', () => {
const bag = propagation.createBaggage({
key: { value: 'value' },
key1: { value: 'value1' },
key2: { value: 'value2' },
});
const bag2 = bag.removeEntries('key', 'key1');
assert.deepStrictEqual(bag.getAllEntries(), [
['key', { value: 'value' }],
['key1', { value: 'value1' }],
['key2', { value: 'value2' }],
]);
assert.deepStrictEqual(bag2.getAllEntries(), [
['key2', { value: 'value2' }],
]);
});
it('should create an empty bag when it cleared', () => {
const bag = propagation.createBaggage({
key: { value: 'value' },
key1: { value: 'value1' },
});
const bag2 = bag.clear();
assert.deepStrictEqual(bag.getAllEntries(), [
['key', { value: 'value' }],
['key1', { value: 'value1' }],
]);
assert.deepStrictEqual(bag2.getAllEntries(), []);
});
});
describe('context', () => {
it('should set and get a baggage from a context', () => {
const bag = propagation.createBaggage();
const ctx = propagation.setBaggage(ROOT_CONTEXT, bag);
assert.strictEqual(bag, propagation.getBaggage(ctx));
});
});
describe('metadata', () => {
it('should create an opaque object which returns the string unchanged', () => {
const meta = baggageEntryMetadataFromString('this is a string');
assert.strictEqual(meta.toString(), 'this is a string');
});
it('should return an empty string if input is invalid', () => {
//@ts-expect-error only accepts string values
const meta = baggageEntryMetadataFromString(1);
assert.strictEqual(meta.toString(), '');
});
it('should retain metadata', () => {
const bag = propagation.createBaggage({
key: {
value: 'value',
metadata: baggageEntryMetadataFromString('meta'),
},
});
assert.deepStrictEqual(bag.getEntry('key')?.metadata?.toString(), 'meta');
});
});
});

138
api/test/context/NoopContextManager.test.ts Normal file
View File

@ -0,0 +1,138 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import { createContextKey, ROOT_CONTEXT } from '../../src/context/context';
import { NoopContextManager } from '../../src/context/NoopContextManager';
describe('NoopContextManager', () => {
let contextManager: NoopContextManager;
describe('.enable()', () => {
it('should work', () => {
assert.doesNotThrow(() => {
contextManager = new NoopContextManager();
assert(
contextManager.enable() === contextManager,
'should return this'
);
});
});
});
describe('.disable()', () => {
it('should work', () => {
assert.doesNotThrow(() => {
assert(
contextManager.disable() === contextManager,
'should return this'
);
});
contextManager.enable();
});
});
describe('.with()', () => {
it('should run the callback (ROOT_CONTEXT as target)', done => {
contextManager.with(ROOT_CONTEXT, done);
});
it('should run the callback (object as target)', done => {
const key = createContextKey('test key 1');
const test = ROOT_CONTEXT.setValue(key, 1);
contextManager.with(test, () => {
assert.strictEqual(
contextManager.active(),
ROOT_CONTEXT,
'should not have context'
);
return done();
});
});
it('should run the callback (when disabled)', done => {
contextManager.disable();
contextManager.with(ROOT_CONTEXT, () => {
contextManager.enable();
return done();
});
});
it('should forward this, arguments and return value', () => {
function fnWithThis(this: string, a: string, b: number): string {
assert.strictEqual(this, 'that');
assert.strictEqual(arguments.length, 2);
assert.strictEqual(a, 'one');
assert.strictEqual(b, 2);
return 'done';
}
const res = contextManager.with(
ROOT_CONTEXT,
fnWithThis,
'that',
'one',
2
);
assert.strictEqual(res, 'done');
assert.strictEqual(
contextManager.with(ROOT_CONTEXT, () => 3.14),
3.14
);
});
});
describe('.active()', () => {
it('should always return ROOT_CONTEXT (when enabled)', () => {
assert.strictEqual(
contextManager.active(),
ROOT_CONTEXT,
'should not have context'
);
});
it('should always return ROOT_CONTEXT (when disabled)', () => {
contextManager.disable();
assert.strictEqual(
contextManager.active(),
ROOT_CONTEXT,
'should not have context'
);
contextManager.enable();
});
});
describe('.bind()', () => {
it('should return the same target (when enabled)', () => {
const test = { a: 1 };
assert.deepStrictEqual(
contextManager.bind(contextManager.active(), test),
test
);
});
it('should return the same target (when disabled)', () => {
contextManager.disable();
const test = { a: 1 };
assert.deepStrictEqual(
contextManager.bind(contextManager.active(), test),
test
);
contextManager.enable();
});
});
});

61
api/test/diag/ComponentLogger.test.ts Normal file
View File

@ -0,0 +1,61 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import * as sinon from 'sinon';
import { diag, DiagLogger, DiagLogLevel } from '../../src';
class SpyLogger implements DiagLogger {
debug() {}
error() {}
info() {}
warn() {}
verbose() {}
}
const loggerFunctions = ['verbose', 'debug', 'info', 'warn', 'error'];
describe('ComponentLogger', () => {
let logger: DiagLogger;
const sandbox = sinon.createSandbox();
beforeEach(() => {
logger = new SpyLogger();
sandbox.spy(logger);
diag.setLogger(logger, DiagLogLevel.ALL);
// clean any messages up that might be there from the registration
sandbox.reset();
});
afterEach(() => {
sandbox.restore();
});
loggerFunctions.forEach(name => {
const fName = name as keyof SpyLogger;
it(`should call global logger function "${name}" with namespace as first param`, () => {
const componentLogger = diag.createComponentLogger({ namespace: 'foo' });
componentLogger[fName]('test');
assert.strictEqual((logger[fName] as sinon.SinonSpy).callCount, 1);
assert.deepStrictEqual((logger[fName] as sinon.SinonSpy).args[0], [
'foo',
'test',
]);
});
});
});

218
api/test/diag/consoleLogger.test.ts Normal file
View File

@ -0,0 +1,218 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/* eslint-disable no-console */
import * as assert from 'assert';
import { DiagConsoleLogger } from '../../src/diag/consoleLogger';
export const diagLoggerFunctions = [
'verbose',
'debug',
'info',
'warn',
'error',
] as const;
const consoleFuncs: Array<keyof Console> = [
'debug',
'info',
'warn',
'error',
'log',
'trace',
];
const expectedConsoleMap: { [n: string]: keyof Console } = {
error: 'error',
warn: 'warn',
info: 'info',
debug: 'debug',
verbose: 'trace',
};
describe('DiagConsoleLogger', () => {
const origConsole = console;
const orig: any = {};
const calledArgs: any = {};
// Save original functions
consoleFuncs.forEach(fName => {
orig[fName] = console[fName];
calledArgs[fName] = null;
});
let canMockConsole = true;
try {
// eslint-disable-next-line no-global-assign
console = origConsole;
} catch (ex) {
// Not supported on CI pipeline (works locally)
canMockConsole = false;
}
beforeEach(() => {
// mock Console
consoleFuncs.forEach(fName => {
console[fName] = (...args: unknown[]) => {
calledArgs[fName] = args;
};
});
});
afterEach(() => {
// restore
if (canMockConsole) {
try {
// eslint-disable-next-line no-global-assign
console = origConsole;
} catch (ex) {
// Not supported on CI pipeline
canMockConsole = false;
}
}
consoleFuncs.forEach(fName => {
calledArgs[fName] = null;
console[fName] = orig[fName];
});
});
describe('constructor', () => {
diagLoggerFunctions.forEach(fName => {
it(`console logger should provide ${fName} function`, () => {
const consoleLogger: any = new DiagConsoleLogger();
consoleLogger[fName](`${fName} called %s`, 'param1');
assert.ok(
typeof consoleLogger[fName] === 'function',
`Must have a ${fName} function`
);
});
it(`should log ${expectedConsoleMap[fName]} message with ${fName} call only`, () => {
const consoleLogger: any = new DiagConsoleLogger();
consoleLogger[fName](`${fName} called %s`, 'param1');
// Make sure only gets logged once
let matches = 0;
consoleFuncs.forEach(cName => {
if (cName !== expectedConsoleMap[fName]) {
assert.deepStrictEqual(calledArgs[cName], null);
} else {
assert.deepStrictEqual(calledArgs[expectedConsoleMap[fName]], [
`${fName} called %s`,
'param1',
]);
matches++;
}
});
assert.deepStrictEqual(calledArgs.log, null);
assert.strictEqual(matches, 1, 'should log at least once');
});
consoleFuncs.forEach(cName => {
it(`should log ${fName} message even when console doesn't support ${cName} call before construction`, () => {
console[cName] = undefined;
const consoleLogger: any = new DiagConsoleLogger();
consoleLogger[fName](`${fName} called %s`, 'param1');
if (cName !== expectedConsoleMap[fName]) {
assert.deepStrictEqual(calledArgs[cName], null);
} else {
assert.deepStrictEqual(calledArgs.log, [
`${fName} called %s`,
'param1',
]);
}
});
it(`should log ${fName} message even when console doesn't support ${cName} call after construction`, () => {
const consoleLogger: any = new DiagConsoleLogger();
console[cName] = undefined;
consoleLogger[fName](`${fName} called %s`, 'param1');
if (cName !== expectedConsoleMap[fName]) {
assert.deepStrictEqual(calledArgs[cName], null);
} else {
assert.deepStrictEqual(calledArgs.log, [
`${fName} called %s`,
'param1',
]);
}
});
});
});
if (canMockConsole) {
diagLoggerFunctions.forEach(fName => {
const cName = expectedConsoleMap[fName];
it(`should not throw even when console is not supported for ${fName} call`, () => {
// eslint-disable-next-line no-global-assign
(console as any) = undefined;
const consoleLogger: any = new DiagConsoleLogger();
consoleLogger[fName](`${fName} called %s`, 'param1');
assert.deepStrictEqual(calledArgs[cName], null);
assert.deepStrictEqual(calledArgs.log, null);
});
it(`should not throw even when console is disabled after construction for ${fName} call`, () => {
const consoleLogger: any = new DiagConsoleLogger();
// eslint-disable-next-line no-global-assign
(console as any) = undefined;
consoleLogger[fName](`${fName} called %s`, 'param1');
assert.deepStrictEqual(calledArgs[expectedConsoleMap[fName]], null);
assert.deepStrictEqual(calledArgs.log, null);
});
it(`should not throw even when console is invalid after construction for ${fName} call`, () => {
const invalidConsole = {
debug: 1,
warn: 2,
error: 3,
trace: 4,
info: 5,
log: 6,
};
const consoleLogger = new DiagConsoleLogger();
// eslint-disable-next-line no-global-assign
(console as any) = invalidConsole;
consoleLogger[fName](`${fName} called %s`, 'param1');
assert.deepStrictEqual(calledArgs[expectedConsoleMap[fName]], null);
assert.deepStrictEqual(calledArgs.log, null);
});
it(`should not throw even when console is invalid before construction for ${fName} call`, () => {
const invalidConsole = {
debug: 1,
warn: 2,
error: 3,
trace: 4,
info: 5,
log: 6,
};
// eslint-disable-next-line no-global-assign
(console as any) = invalidConsole;
const consoleLogger = new DiagConsoleLogger();
consoleLogger[fName](`${fName} called %s`, 'param1');
assert.deepStrictEqual(calledArgs[expectedConsoleMap[fName]], null);
assert.deepStrictEqual(calledArgs.log, null);
});
});
}
});
});

236
api/test/diag/logLevel.test.ts Normal file
View File

@ -0,0 +1,236 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import { diag } from '../../src';
import { createLogLevelDiagLogger } from '../../src/diag/internal/logLevelLogger';
import { createNoopDiagLogger } from '../../src/diag/internal/noopLogger';
import { DiagLogger, DiagLogLevel } from '../../src/diag/types';
// Matches the previous Logger definition
const incompleteLoggerFuncs = ['debug', 'info', 'warn', 'error'] as const;
export const diagLoggerFunctions = [
'verbose',
'debug',
'info',
'warn',
'error',
] as const;
describe('LogLevelFilter DiagLogger', () => {
const calledArgs: any = {
error: null,
warn: null,
info: null,
debug: null,
verbose: null,
};
let dummyLogger: DiagLogger;
/** Simulated Legacy logger */
let incompleteLogger: DiagLogger;
const restoreCallHistory = () => {
diagLoggerFunctions.forEach(fName => {
calledArgs[fName] = null;
});
};
beforeEach(() => {
// Set no logger so that sinon doesn't complain about TypeError: Attempted to wrap xxxx which is already wrapped
diag.disable();
// mock
dummyLogger = {} as DiagLogger;
diagLoggerFunctions.forEach(fName => {
dummyLogger[fName] = (...args: unknown[]) => {
calledArgs[fName] = args;
};
});
incompleteLogger = {} as DiagLogger;
incompleteLoggerFuncs.forEach(fName => {
incompleteLogger[fName] = (...args: unknown[]) => {
calledArgs[fName] = args;
};
});
});
afterEach(() => {
restoreCallHistory();
});
const levelMap: Array<{
message: string;
level: DiagLogLevel;
ignoreFuncs: Array<keyof DiagLogger>;
}> = [
{ message: 'ALL', level: DiagLogLevel.ALL, ignoreFuncs: [] },
{ message: 'greater than ALL', level: 32768, ignoreFuncs: [] },
{ message: 'VERBOSE', level: DiagLogLevel.VERBOSE, ignoreFuncs: [] },
{ message: 'DEBUG', level: DiagLogLevel.DEBUG, ignoreFuncs: ['verbose'] },
{
message: 'INFO',
level: DiagLogLevel.INFO,
ignoreFuncs: ['verbose', 'debug'],
},
{
message: 'WARN',
level: DiagLogLevel.WARN,
ignoreFuncs: ['verbose', 'debug', 'info'],
},
{
message: 'ERROR',
level: DiagLogLevel.ERROR,
ignoreFuncs: ['verbose', 'debug', 'info', 'warn'],
},
{
message: 'between ERROR and NONE',
level: 1,
ignoreFuncs: ['verbose', 'debug', 'info', 'warn', 'error'],
},
{
message: 'NONE',
level: DiagLogLevel.NONE,
ignoreFuncs: ['verbose', 'debug', 'info', 'warn', 'error'],
},
{
message: 'less than NONE',
level: -1000,
ignoreFuncs: ['verbose', 'debug', 'info', 'warn', 'error'],
},
];
levelMap.forEach(map => {
describe(`with ${map.message} log level`, () => {
diagLoggerFunctions.forEach(fName => {
describe(`calling ${fName} message`, () => {
it('should log', () => {
const testLogger = createLogLevelDiagLogger(map.level, dummyLogger);
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
if (fName === lName && map.ignoreFuncs.indexOf(lName) === -1) {
assert.deepStrictEqual(calledArgs[lName], [
`${fName} called %s`,
'param1',
]);
} else {
assert.strictEqual(calledArgs[lName], null);
}
});
});
it('should be noop for null with explicit noop Logger log', () => {
const testLogger = createLogLevelDiagLogger(
map.level,
createNoopDiagLogger()
);
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
assert.strictEqual(calledArgs[lName], null);
});
});
it('should be noop and not throw for null and no default Logger log', () => {
// @ts-expect-error null logger is not allowed
const testLogger = createLogLevelDiagLogger(map.level, null);
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
assert.strictEqual(calledArgs[lName], null);
});
});
it('should be noop and not throw for undefined and no default Logger log', () => {
// @ts-expect-error undefined logger is not allowed
const testLogger = createLogLevelDiagLogger(map.level, undefined);
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
assert.strictEqual(calledArgs[lName], null);
});
});
levelMap.forEach(masterLevelMap => {
describe(`when diag logger is set to ${masterLevelMap.message}`, () => {
it('diag.setLogger level is ignored when using a specific logger', () => {
diag.setLogger(dummyLogger, masterLevelMap.level);
const testLogger = createLogLevelDiagLogger(
map.level,
dummyLogger
);
restoreCallHistory();
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
if (
fName === lName &&
map.ignoreFuncs.indexOf(lName) === -1
) {
assert.deepStrictEqual(calledArgs[lName], [
`${fName} called %s`,
'param1',
]);
} else {
assert.strictEqual(calledArgs[lName], null);
}
});
});
});
});
it('diag.setLogger level and logger should log', () => {
diag.setLogger(dummyLogger, map.level);
restoreCallHistory();
diag[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
if (fName === lName && map.ignoreFuncs.indexOf(lName) === -1) {
assert.deepStrictEqual(calledArgs[lName], [
`${fName} called %s`,
'param1',
]);
} else {
assert.strictEqual(calledArgs[lName], null);
}
});
});
it('should not throw with an invalid DiagLogger', () => {
const invalidLogger = {
debug: 1,
warn: 2,
error: 3,
trace: 4,
info: 5,
log: 6,
};
const testLogger = createLogLevelDiagLogger(
map.level,
invalidLogger as any
);
restoreCallHistory();
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
assert.strictEqual(calledArgs[lName], null);
});
});
});
});
});
});
});

126
api/test/diag/logger.test.ts Normal file
View File

@ -0,0 +1,126 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import sinon = require('sinon');
import { diag, DiagLogLevel } from '../../src';
import { createNoopDiagLogger } from '../../src/diag/internal/noopLogger';
import { DiagLogger } from '../../src/diag/types';
export const diagLoggerFunctions = [
'verbose',
'debug',
'info',
'warn',
'error',
] as const;
describe('DiagLogger functions', () => {
const calledArgs: any = {
error: null,
warn: null,
info: null,
debug: null,
verbose: null,
};
let dummyLogger: DiagLogger;
const restoreCallHistory = () => {
diagLoggerFunctions.forEach(fName => {
calledArgs[fName] = null;
});
};
beforeEach(() => {
// mock
dummyLogger = {} as DiagLogger;
diagLoggerFunctions.forEach(fName => {
dummyLogger[fName] = (...args: unknown[]) => {
calledArgs[fName] = args;
};
});
});
afterEach(() => {
restoreCallHistory();
diag.disable();
});
describe('constructor', () => {
diagLoggerFunctions.forEach(fName => {
it(`should log with ${fName} message`, () => {
const testLogger = dummyLogger;
testLogger[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
if (fName === lName) {
assert.deepStrictEqual(calledArgs[fName], [
`${fName} called %s`,
'param1',
]);
} else {
assert.strictEqual(calledArgs[lName], null);
}
});
});
it(`diag should log with ${fName} message`, () => {
diag.setLogger(dummyLogger, DiagLogLevel.ALL);
restoreCallHistory();
diag[fName](`${fName} called %s`, 'param1');
diagLoggerFunctions.forEach(lName => {
if (fName === lName) {
assert.deepStrictEqual(calledArgs[fName], [
`${fName} called %s`,
'param1',
]);
} else {
assert.strictEqual(calledArgs[lName], null);
}
});
});
it(`NoopLogger should implement all functions and not throw when ${fName} called`, () => {
const testLogger = createNoopDiagLogger();
assert.ok(typeof testLogger[fName], 'function');
testLogger[fName](`${fName} called %s`, 'param1');
});
});
});
describe('diag is used as the diag logger in setLogger', () => {
it('should not throw', () => {
diag.setLogger(diag);
});
it('should use the previously registered logger to log the error', () => {
const error = sinon.stub();
diag.setLogger({
verbose: () => {},
debug: () => {},
info: () => {},
warn: () => {},
error,
});
sinon.assert.notCalled(error);
diag.setLogger(diag);
sinon.assert.calledOnce(error);
});
});
});

20
api/test/index-webpack.ts Normal file
View File

@ -0,0 +1,20 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
const testsContext = require.context('.', true, /test$/);
testsContext.keys().forEach(testsContext);
const srcContext = require.context('.', true, /src$/);
srcContext.keys().forEach(srcContext);

155
api/test/internal/global.test.ts Normal file
View File

@ -0,0 +1,155 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import { getGlobal } from '../../src/internal/global-utils';
import { _globalThis } from '../../src/platform';
import { NoopContextManager } from '../../src/context/NoopContextManager';
import { DiagLogLevel } from '../../src/diag/types';
import sinon = require('sinon');
const api1 = require('../../src') as typeof import('../../src');
// clear cache and load a second instance of the api
for (const key of Object.keys(require.cache)) {
delete require.cache[key];
}
const api2 = require('../../src') as typeof import('../../src');
// This will need to be changed manually on major version changes.
// It is intentionally not autogenerated to ensure the author of the change is aware of what they are doing.
const GLOBAL_API_SYMBOL_KEY = 'opentelemetry.js.api.1';
const getMockLogger = () => ({
verbose: sinon.spy(),
debug: sinon.spy(),
info: sinon.spy(),
warn: sinon.spy(),
error: sinon.spy(),
});
describe('Global Utils', () => {
// prove they are separate instances
assert.notEqual(api1, api2);
// that return separate noop instances to start
assert.notStrictEqual(
api1.context['_getContextManager'](),
api2.context['_getContextManager']()
);
beforeEach(() => {
api1.context.disable();
api1.propagation.disable();
api1.trace.disable();
api1.diag.disable();
// @ts-expect-error we are modifying internals for testing purposes here
delete _globalThis[Symbol.for(GLOBAL_API_SYMBOL_KEY)];
});
it('should change the global context manager', () => {
const original = api1.context['_getContextManager']();
const newContextManager = new NoopContextManager();
api1.context.setGlobalContextManager(newContextManager);
assert.notStrictEqual(api1.context['_getContextManager'](), original);
assert.strictEqual(api1.context['_getContextManager'](), newContextManager);
});
it('should load an instance from one which was set in the other', () => {
api1.context.setGlobalContextManager(new NoopContextManager());
assert.strictEqual(
api1.context['_getContextManager'](),
api2.context['_getContextManager']()
);
});
it('should disable both if one is disabled', () => {
const manager = new NoopContextManager();
api1.context.setGlobalContextManager(manager);
assert.strictEqual(manager, api1.context['_getContextManager']());
api2.context.disable();
assert.notStrictEqual(manager, api1.context['_getContextManager']());
});
it('should return the module NoOp implementation if the version is a mismatch', () => {
const newContextManager = new NoopContextManager();
api1.context.setGlobalContextManager(newContextManager);
// ensure new context manager is returned
assert.strictEqual(api1.context['_getContextManager'](), newContextManager);
const globalInstance = getGlobal('context');
assert.ok(globalInstance);
// @ts-expect-error we are modifying internals for testing purposes here
_globalThis[Symbol.for(GLOBAL_API_SYMBOL_KEY)].version = '0.0.1';
// ensure new context manager is not returned because version above is incompatible
assert.notStrictEqual(
api1.context['_getContextManager'](),
newContextManager
);
});
it('should debug log registrations', () => {
const logger = getMockLogger();
api1.diag.setLogger(logger, DiagLogLevel.DEBUG);
const newContextManager = new NoopContextManager();
api1.context.setGlobalContextManager(newContextManager);
sinon.assert.calledWith(logger.debug, sinon.match(/global for context/));
sinon.assert.calledWith(logger.debug, sinon.match(/global for diag/));
sinon.assert.calledTwice(logger.debug);
});
it('should log an error if there is a duplicate registration', () => {
const logger = getMockLogger();
api1.diag.setLogger(logger);
api1.context.setGlobalContextManager(new NoopContextManager());
api1.context.setGlobalContextManager(new NoopContextManager());
sinon.assert.calledOnce(logger.error);
assert.strictEqual(logger.error.firstCall.args.length, 1);
assert.ok(
logger.error.firstCall.args[0].startsWith(
'Error: @opentelemetry/api: Attempted duplicate registration of API: context'
)
);
});
it('should allow duplicate registration of the diag logger', () => {
const logger1 = getMockLogger();
const logger2 = getMockLogger();
api1.diag.setLogger(logger1);
api1.diag.setLogger(logger2);
const MSG = '__log message__';
api1.diag.info(MSG);
sinon.assert.notCalled(logger1.error);
sinon.assert.notCalled(logger1.info);
sinon.assert.calledOnce(logger1.warn);
sinon.assert.calledWith(logger1.warn, sinon.match(/will be overwritten/i));
sinon.assert.notCalled(logger2.error);
sinon.assert.calledOnce(logger2.warn);
sinon.assert.calledWith(logger2.warn, sinon.match(/will overwrite/i));
sinon.assert.calledOnce(logger2.info);
sinon.assert.calledWith(logger2.info, MSG);
});
});

148
api/test/internal/semver.test.ts Normal file
View File

@ -0,0 +1,148 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import {
isCompatible,
_makeCompatibilityCheck,
} from '../../src/internal/semver';
import { VERSION } from '../../src/version';
describe('semver', () => {
it('should be compatible if versions are equal', () => {
assert.ok(isCompatible(VERSION));
});
it('returns false if own version cannot be parsed', () => {
const check = _makeCompatibilityCheck('this is not semver');
assert.ok(!check('1.0.0'));
});
it('incompatible if other version cannot be parsed', () => {
const check = _makeCompatibilityCheck('0.1.2');
assert.ok(!check('this is not semver'));
});
describe('>= 1.0.0', () => {
const globalVersion = '5.5.5';
const vers: [string, boolean][] = [
// same major/minor run should be compatible
['5.5.5', true],
['5.5.6', true],
['5.5.4', true],
// prerelease version should not be compatible
['5.5.5-rc.0', false],
// if our version has a minor version increase, we may try to call methods which don't exist on the global
['5.6.5', false],
['5.6.6', false],
['5.6.4', false],
// if the global version is ahead of us by a minor revision, it has at least the methods we know about
['5.4.5', true],
['5.4.6', true],
['5.4.4', true],
// major version mismatch is always incompatible
['6.5.5', false],
['6.5.6', false],
['6.5.4', false],
['6.6.5', false],
['6.6.6', false],
['6.6.4', false],
['6.4.5', false],
['6.4.6', false],
['6.4.4', false],
['4.5.5', false],
['4.5.6', false],
['4.5.4', false],
['4.6.5', false],
['4.6.6', false],
['4.6.4', false],
['4.4.5', false],
['4.4.6', false],
['4.4.4', false],
];
test(globalVersion, vers);
});
describe('< 1.0.0', () => {
const globalVersion = '0.5.5';
const vers: [string, boolean][] = [
// same minor/patch should be compatible
['0.5.5', true],
// prerelease version should not be compatible
['0.5.5-rc.0', false],
// if our version has a patch version increase, we may try to call methods which don't exist on the global
['0.5.6', false],
// if the global version is ahead of us by a patch revision, it has at least the methods we know about
['0.5.4', true],
// minor version mismatch is always incompatible
['0.6.5', false],
['0.6.6', false],
['0.6.4', false],
['0.4.5', false],
['0.4.6', false],
['0.4.4', false],
// major version mismatch is always incompatible
['1.5.5', false],
['1.5.6', false],
['1.5.4', false],
['1.6.5', false],
['1.6.6', false],
['1.6.4', false],
['1.4.5', false],
['1.4.6', false],
['1.4.4', false],
];
test(globalVersion, vers);
});
describe('global version is prerelease', () => {
const globalVersion = '1.0.0-rc.3';
const vers: [string, boolean][] = [
// must match exactly
['1.0.0', false],
['1.0.0-rc.2', false],
['1.0.0-rc.4', false],
['1.0.0-rc.3', true],
];
test(globalVersion, vers);
});
});
function test(globalVersion: string, vers: [string, boolean][]) {
describe(`global version is ${globalVersion}`, () => {
for (const [version, compatible] of vers) {
it(`API version ${version} ${
compatible ? 'should' : 'should not'
} be able to access global`, () => {
const check = _makeCompatibilityCheck(version);
assert.strictEqual(check(globalVersion), compatible);
});
}
});
}

30
api/test/internal/version.test.ts Normal file
View File

@ -0,0 +1,30 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import { VERSION } from '../../src/version';
describe('version', () => {
it('should have generated VERSION.ts', () => {
const pjson = require('../../package.json');
assert.strictEqual(pjson.version, VERSION);
});
it('prerelease tag versions are banned', () => {
// see https://github.com/open-telemetry/opentelemetry-js-api/issues/74
assert.ok(VERSION.match(/^\d+\.\d+\.\d+$/));
});
});

54
api/test/noop-implementations/noop-span.test.ts Normal file
View File

@ -0,0 +1,54 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import {
SpanStatusCode,
INVALID_SPANID,
INVALID_TRACEID,
TraceFlags,
} from '../../src';
import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan';
describe('NonRecordingSpan', () => {
it('do not crash', () => {
const span = new NonRecordingSpan();
span.setAttribute('my_string_attribute', 'foo');
span.setAttribute('my_number_attribute', 123);
span.setAttribute('my_boolean_attribute', false);
span.setAttribute('my_obj_attribute', { a: true });
span.setAttribute('my_sym_attribute', Symbol('a'));
span.setAttributes({
my_string_attribute: 'foo',
my_number_attribute: 123,
});
span.addEvent('sent');
span.addEvent('sent', { id: '42', key: 'value' });
span.setStatus({ code: SpanStatusCode.ERROR });
span.updateName('my-span');
assert.ok(!span.isRecording());
assert.deepStrictEqual(span.spanContext(), {
traceId: INVALID_TRACEID,
spanId: INVALID_SPANID,
traceFlags: TraceFlags.NONE,
});
span.end();
});
});

31
api/test/noop-implementations/noop-tracer-provider.test.ts Normal file
View File

@ -0,0 +1,31 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import { NoopTracer } from '../../src/trace/NoopTracer';
import { NoopTracerProvider } from '../../src/trace/NoopTracerProvider';
describe('NoopTracerProvider', () => {
it('should not crash', () => {
const tracerProvider = new NoopTracerProvider();
assert.ok(tracerProvider.getTracer('tracer-name') instanceof NoopTracer);
assert.ok(tracerProvider.getTracer('tracer-name', 'v1') instanceof NoopTracer);
assert.ok(tracerProvider.getTracer('tracer-name', 'v1', {
schemaUrl: 'https://opentelemetry.io/schemas/1.7.0'
}) instanceof NoopTracer);
});
});

84
api/test/noop-implementations/noop-tracer.test.ts Normal file
View File

@ -0,0 +1,84 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import {
context,
Span,
SpanContext,
SpanKind,
trace,
TraceFlags,
} from '../../src';
import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan';
import { NoopTracer } from '../../src/trace/NoopTracer';
describe('NoopTracer', () => {
it('should not crash', () => {
const tracer = new NoopTracer();
assert.ok(tracer.startSpan('span-name') instanceof NonRecordingSpan);
assert.ok(
tracer.startSpan('span-name1', { kind: SpanKind.CLIENT }) instanceof
NonRecordingSpan
);
assert.ok(
tracer.startSpan('span-name2', { kind: SpanKind.CLIENT }) instanceof
NonRecordingSpan
);
});
it('should propagate valid spanContext on the span (from context)', () => {
const tracer = new NoopTracer();
const parent: SpanContext = {
traceId: 'd4cda95b652f4a1592b449dd92ffda3b',
spanId: '6e0c63ffe4e34c42',
traceFlags: TraceFlags.NONE,
};
const span = tracer.startSpan(
'test-1',
{},
trace.setSpanContext(context.active(), parent)
);
assert(span.spanContext().traceId === parent.traceId);
assert(span.spanContext().spanId === parent.spanId);
assert(span.spanContext().traceFlags === parent.traceFlags);
});
it('should accept 2 to 4 args and start an active span', () => {
const tracer = new NoopTracer();
const name = 'span-name';
const fn = (span: Span) => {
try {
return 1;
} finally {
span.end();
}
};
const opts = { attributes: { foo: 'bar' } };
assert.strictEqual((tracer as any).startActiveSpan(name), undefined);
assert.strictEqual(tracer.startActiveSpan(name, fn), 1);
assert.strictEqual(tracer.startActiveSpan(name, opts, fn), 1);
assert.strictEqual(
tracer.startActiveSpan(name, opts, context.active(), fn),
1
);
});
});

189
api/test/proxy-implementations/proxy-tracer.test.ts Normal file
View File

@ -0,0 +1,189 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import * as sinon from 'sinon';
import {
context,
ProxyTracer,
ProxyTracerProvider,
ROOT_CONTEXT,
Span,
SpanKind,
SpanOptions,
Tracer,
TracerProvider,
} from '../../src';
import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan';
import { NoopTracer } from '../../src/trace/NoopTracer';
describe('ProxyTracer', () => {
let provider: ProxyTracerProvider;
const sandbox = sinon.createSandbox();
beforeEach(() => {
provider = new ProxyTracerProvider();
});
afterEach(() => {
sandbox.restore();
});
describe('when no delegate is set', () => {
it('should return proxy tracers', () => {
const tracer = provider.getTracer('test');
assert.ok(tracer instanceof ProxyTracer);
});
it('startSpan should return Noop Spans', () => {
const tracer = provider.getTracer('test');
assert.ok(tracer.startSpan('span-name') instanceof NonRecordingSpan);
assert.ok(
tracer.startSpan('span-name1', { kind: SpanKind.CLIENT }) instanceof
NonRecordingSpan
);
assert.ok(
tracer.startSpan('span-name2', { kind: SpanKind.CLIENT }) instanceof
NonRecordingSpan
);
});
});
describe('when delegate is set before getTracer', () => {
let delegate: TracerProvider;
let getTracerStub: sinon.SinonStub;
beforeEach(() => {
getTracerStub = sandbox.stub().returns(new NoopTracer());
delegate = {
getTracer: getTracerStub,
};
provider.setDelegate(delegate);
});
it('should return tracers directly from the delegate', () => {
const tracer = provider.getTracer('test', 'v0');
sandbox.assert.calledOnce(getTracerStub);
assert.strictEqual(getTracerStub.firstCall.returnValue, tracer);
assert.deepStrictEqual(getTracerStub.firstCall.args, [
'test',
'v0',
undefined,
]);
});
it('should return tracers directly from the delegate with schema url', () => {
const tracer = provider.getTracer('test', 'v0', {
schemaUrl: 'https://opentelemetry.io/schemas/1.7.0',
});
sandbox.assert.calledOnce(getTracerStub);
assert.strictEqual(getTracerStub.firstCall.returnValue, tracer);
assert.deepStrictEqual(getTracerStub.firstCall.args, [
'test',
'v0',
{ schemaUrl: 'https://opentelemetry.io/schemas/1.7.0' },
]);
});
});
describe('when delegate is set after getTracer', () => {
let tracer: Tracer;
let delegate: TracerProvider;
let delegateSpan: Span;
let delegateTracer: Tracer;
beforeEach(() => {
delegateSpan = new NonRecordingSpan();
delegateTracer = {
startSpan() {
return delegateSpan;
},
startActiveSpan() {
// stubbed
},
};
tracer = provider.getTracer('test');
delegate = {
getTracer() {
return delegateTracer;
},
};
provider.setDelegate(delegate);
});
it('should create spans using the delegate tracer', () => {
const span = tracer.startSpan('test');
assert.strictEqual(span, delegateSpan);
});
it('should create active spans using the delegate tracer', () => {
// sinon types are broken with overloads, hence the any
// https://github.com/DefinitelyTyped/DefinitelyTyped/issues/36436
const startActiveSpanStub = sinon.stub<Tracer, any>(
delegateTracer,
'startActiveSpan'
);
const name = 'span-name';
const fn = (span: Span) => {
try {
return 1;
} finally {
span.end();
}
};
const opts = { attributes: { foo: 'bar' } };
const ctx = context.active();
startActiveSpanStub.withArgs(name, fn).returns(1);
startActiveSpanStub.withArgs(name, opts, fn).returns(2);
startActiveSpanStub.withArgs(name, opts, ctx, fn).returns(3);
assert.strictEqual(tracer.startActiveSpan(name, fn), 1);
assert.strictEqual(tracer.startActiveSpan(name, opts, fn), 2);
assert.strictEqual(tracer.startActiveSpan(name, opts, ctx, fn), 3);
});
it('should pass original arguments to DelegateTracer#startSpan', () => {
const startSpanStub = sandbox.stub(delegateTracer, 'startSpan');
const name = 'name1';
const options: SpanOptions = {};
const ctx = ROOT_CONTEXT.setValue(Symbol('test'), 1);
tracer.startSpan(name, options, ctx);
// Assert the proxy tracer has the full API of the NoopTracer
assert.strictEqual(
NoopTracer.prototype.startSpan.length,
ProxyTracer.prototype.startSpan.length
);
assert.deepStrictEqual(Object.getOwnPropertyNames(NoopTracer.prototype), [
'constructor',
'startSpan',
'startActiveSpan',
]);
sandbox.assert.calledOnceWithExactly(startSpanStub, name, options, ctx);
});
});
});

70
api/test/trace/spancontext-utils.test.ts Normal file
View File

@ -0,0 +1,70 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import * as context from '../../src/trace/spancontext-utils';
import { INVALID_SPANID, INVALID_TRACEID, TraceFlags } from '../../src';
describe('spancontext-utils', () => {
it('should return true for valid spancontext', () => {
const spanContext = {
traceId: 'd4cda95b652f4a1592b449d5929fda1b',
spanId: '6e0c63257de34c92',
traceFlags: TraceFlags.NONE,
};
assert.ok(context.isSpanContextValid(spanContext));
});
it('should return false when traceId is invalid', () => {
const spanContext = {
traceId: INVALID_TRACEID,
spanId: '6e0c63257de34c92',
traceFlags: TraceFlags.NONE,
};
assert.ok(!context.isSpanContextValid(spanContext));
});
it('should return false when spanId is invalid', () => {
const spanContext = {
traceId: 'd4cda95b652f4a1592b449d5929fda1b',
spanId: INVALID_SPANID,
traceFlags: TraceFlags.NONE,
};
assert.ok(!context.isSpanContextValid(spanContext));
});
it('should return false when traceId & spanId is invalid', () => {
const spanContext = {
traceId: INVALID_TRACEID,
spanId: INVALID_SPANID,
traceFlags: TraceFlags.NONE,
};
assert.ok(!context.isSpanContextValid(spanContext));
});
it('should wrap a SpanContext in a non-recording span', () => {
const spanContext = {
traceId: 'd4cda95b652f4a1592b449d5929fda1b',
spanId: '6e0c63257de34c92',
traceFlags: TraceFlags.NONE,
};
const span = context.wrapSpanContext(spanContext);
assert.deepStrictEqual(span.spanContext(), spanContext);
assert.strictEqual(span.isRecording(), false);
});
});

92
api/test/trace/tracestate-validators.test.ts Normal file
View File

@ -0,0 +1,92 @@
/*
* Copyright The OpenTelemetry Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as assert from 'assert';
import { validateKey, validateValue } from '../../src/trace/internal/tracestate-validators';
describe('validators', () => {
describe('validateKey', () => {
const validKeysTestCases = [
'abcdefghijklmnopqrstuvwxyz0123456789-_*/',
'baz-',
'baz_',
'baz*',
'baz*bar',
'baz/',
'tracestate',
'fw529a3039@dt',
'6cab5bb-29a@dt',
];
validKeysTestCases.forEach(testCase =>
it(`returns true when key contains valid chars ${testCase}`, () => {
assert.ok(validateKey(testCase), `${testCase} should be valid`);
})
);
const invalidKeysTestCases = [
'1_key',
'kEy_1',
'k'.repeat(257),
'key,',
'TrAcEsTaTE',
'TRACESTATE',
'',
'6num',
];
invalidKeysTestCases.forEach(testCase =>
it(`returns true when key contains invalid chars ${testCase}`, () => {
assert.ok(!validateKey(testCase), `${testCase} should be invalid`);
})
);
});
describe('validateValue', () => {
const validValuesTestCases = [
'first second',
'baz*',
'baz$',
'baz@',
'first-second',
'baz~bar',
'test-v1:120',
'-second',
'first.second',
'TrAcEsTaTE',
'TRACESTATE',
];
validValuesTestCases.forEach(testCase =>
it(`returns true when value contains valid chars ${testCase}`, () => {
assert.ok(validateValue(testCase));
})
);
const invalidValuesTestCases = [
'my_value=5',
'first,second',
'first ',
'k'.repeat(257),
',baz',
'baz,',
'baz=',
'',
];
invalidValuesTestCases.forEach(testCase =>
it(`returns true when value contains invalid chars ${testCase}`, () => {
assert.ok(!validateValue(testCase));
})
);
});
});

Some files were not shown because too many files have changed in this diff Show More