Merge branch 'main' into plugins

.github/ISSUE_TEMPLATE/bug_report.md

@@ -4,7 +4,9 @@ about: Create a report to help us improve
 labels: bug
 ---
 
+<!-- 
 Please answer these questions before submitting a bug report.
+-->
 
 ### What version of OpenTelemetry are you using?
 
@@ -13,7 +15,9 @@ Please answer these questions before submitting a bug report.
 
 
 ### What did you do?
+<!-- 
 If possible, provide a recipe for reproducing the error.
+-->
 
 
 ### What did you expect to see?
@@ -23,4 +27,7 @@ If possible, provide a recipe for reproducing the error.
 
 
 ### Additional context
+<!-- 
 Add any other context about the problem here.
+-->
+

.github/ISSUE_TEMPLATE/discussion.md

@@ -10,3 +10,4 @@ labels: discussion
 
 - [ ] This only affects the JavaScript OpenTelemetry library
 - [ ] This may affect other libraries, but I would like to get opinions here first
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -4,17 +4,30 @@ about: Suggest an idea for this project
 labels: feature-request
 ---
 
+<!--
 **NB:** Before opening a feature request against this repo, consider whether the feature should/could be implemented in the [other OpenTelemetry client libraries](https://github.com/open-telemetry/). If so, please [open an issue on opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification/issues/new) first.
+-->
 
-
-**Is your feature request related to a problem? Please describe.**
+### Is your feature request related to a problem? Please describe
+<!--
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+-->
+
 
-**Describe the solution you'd like**
+### Describe the solution you'd like to see
+<!-- 
 A clear and concise description of what you want to happen.
+-->
+
 
-**Describe alternatives you've considered**
+### Describe alternatives you've considered
+<!-- 
 A clear and concise description of any alternative solutions or features you've considered.
+-->
 
-**Additional context**
+
+### Additional context
+<!-- 
 Add any other context or screenshots about the feature request here.
+-->
+

.github/ISSUE_TEMPLATE/plugin_request.md

@@ -1,30 +1,32 @@
 ---
-name: Plugin request
-about: Create a report to add support for plugin
-labels: plugin-request
+name: Instrumentation request
+about: Create a report to add support for an instrumentation
+labels: instrumentation-request
 ---
 
 <!--
-**NB:** Before opening a plugin support request against this repo, consider whether the plugin should/could be implemented in the [other OpenTelemetry client libraries](https://github.com/open-telemetry/). If so, please [open an issue on opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification/issues/new) first.
+**NB:** Before opening an instrumentation request against this repo, consider whether the instrumentation should/could be implemented in the [other OpenTelemetry client libraries](https://github.com/open-telemetry/). If so, please [open an issue on opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification/issues/new) first.
 
-You are welcome to try out the [plugin api](https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/plugin-guide.md) to build your own plugin. If you do try out the plugin api, please let us know if you have any questions/feedback.
+You are welcome to try to build your own instrumentation. If you do, please let us know if you have any questions/feedback.
 -->
 
-**Is your plugin request related to a problem? Please describe.**
+### Is your instrumentation request related to a problem? Please describe
 <!--
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 -->
 
-**Is it applicable for Node or Browser or both**
 
-**Do you expect this plugin to be commonly used**
+### Is it applicable for Node or Browser or both?
+
+
+### Do you expect this instrumentation to be commonly used?
 Weekly Downloads:
 
-**What version of plugin are you interested in using**
+### What version of instrumentation are you interested in using?
 Versions:
 
-**Additional context**
+### Additional context
 <!--
-Add any other context or screenshots about the plugin request here.
+Add any other context or screenshots about the instrumentation request here. Is there a reference you could point for the well-defined lifecycle methods?
 -->
-- **Is there a reference you could point for the well-defined lifecycle methods**
+

examples/restify/README.md

@@ -0,0 +1,45 @@
+# Overview
+
+OpenTelemetry Restify Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (we can use Zipkin or Jaeger for this example). This example demonstrates tracing calls made to Restify API. All generated spans include following attributes:
+
+- `http.route`: resolved route;
+- `restify.method`: server method used to register the handler. One of `use`, `pre`, `del`, `get`, `head`, `opts`, `post`, `put` or `patch`;
+- `restify.type`: either `middleware` or `request_handler`;
+- `restify.version`: `restify` version running.
+
+## Setup
+
+Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html)
+or
+Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Run the Application
+
+First install the dependencies:
+
+```sh
+npm install
+```
+
+### Zipkin
+
+```sh
+npm run zipkin:server # Run the server
+npm run zipkin:client # Run the client in a separate terminal
+```
+
+### Jaeger
+
+```sh
+npm run jaeger:server # Run the server
+npm run jaeger:client # Run the client in a separate terminal
+```
+
+## Useful links
+
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-node>
+
+## LICENSE
+
+Apache License 2.0

examples/restify/client.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// required to initialize the service name for the auto-instrumentation
+require('./tracer')('example-restify-client');
+// eslint-disable-next-line import/order
+const http = require('http');
+
+/** A function which makes requests and handles response. */
+function makeRequest(path) {
+  // span corresponds to outgoing requests. Here, we have manually created
+  // the span, which is created to track work that happens outside of the
+  // request lifecycle entirely.
+  http.get({
+    host: 'localhost',
+    headers: {
+      accept: 'text/plain',
+    },
+    port: 8080,
+    path,
+  }, (response) => {
+    response.on('data', (chunk) => console.log(path, '::', chunk.toString('utf8')));
+    response.on('end', () => {
+      console.log(path, 'status', response.statusCode);
+    });
+  });
+
+  // The process must live for at least the interval past any traces that
+  // must be exported, or some risk being lost if they are recorded after the
+  // last export.
+  console.log('Sleeping 5 seconds before shutdown to ensure all records are flushed.');
+  setTimeout(() => { console.log('Completed.'); }, 5000);
+}
+
+makeRequest('/hello/world');
+makeRequest('/bye/world');

examples/restify/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "restify-example",
+  "private": true,
+  "version": "0.18.0",
+  "description": "Example of restify integration with OpenTelemetry",
+  "main": "index.js",
+  "scripts": {
+    "zipkin:server": "cross-env EXPORTER=zipkin node ./server.js",
+    "zipkin:client": "cross-env EXPORTER=zipkin node ./client.js",
+    "jaeger:server": "cross-env EXPORTER=jaeger node ./server.js",
+    "jaeger:client": "cross-env EXPORTER=jaeger node ./client.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "http",
+    "tracing"
+  ],
+  "engines": {
+    "node": ">=8"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js/issues"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^0.18.0",
+    "@opentelemetry/exporter-jaeger": "^0.18.0",
+    "@opentelemetry/exporter-zipkin": "^0.18.0",
+    "@opentelemetry/instrumentation": "^0.18.0",
+    "@opentelemetry/instrumentation-http": "^0.18.0",
+    "@opentelemetry/node": "^0.18.0",
+    "@opentelemetry/tracing": "^0.18.0",
+    "restify": "^4.3.4"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

examples/restify/server.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const api = require('@opentelemetry/api');
+
+const { diag, DiagConsoleLogger, DiagLogLevel } = api;
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.VERBOSE);
+
+const restify = require('restify');
+require('./tracer')('example-restify-server');
+
+const server = restify.createServer();
+const PORT = 8080;
+
+server.pre((req, res, next) => {
+  next();
+});
+
+// `setDefaultName` shows up in spans as the name
+const setDefaultName = (req, res, next) => {
+  req.defaultName = 'Stranger';
+  next();
+};
+
+server.use([(req, res, next) => {
+  /*
+    noop to showcase use with an array.
+    as this is an anonymous fn, the name is not known and cannot be displayed in traces.
+   */
+  next();
+}, setDefaultName]);
+
+// named function to be used in traces
+// eslint-disable-next-line prefer-arrow-callback
+server.get('/hello/:name', function hello(req, res, next) {
+  console.log('Handling hello');
+  res.send(`Hello, ${req.params.name || req.defaultName}\n`);
+  return next();
+});
+
+server.get('/bye/:name', (req, res, next) => {
+  console.log('Handling bye');
+  return next(new Error('Ooops in bye'));
+});
+
+server.listen(PORT, () => {
+  console.log('Ready on %s', server.url);
+});

examples/restify/tracer.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/api');
+
+const { diag, DiagConsoleLogger, DiagLogLevel } = opentelemetry;
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.VERBOSE);
+
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+const { NodeTracerProvider } = require('@opentelemetry/node');
+const { SimpleSpanProcessor, ConsoleSpanExporter } = require('@opentelemetry/tracing');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
+
+const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
+const { RestifyInstrumentation } = require('@opentelemetry/instrumentation-restify');
+
+const Exporter = ((exporterParam) => {
+  if (typeof exporterParam === 'string') {
+    const exporterString = exporterParam.toLowerCase();
+    if (exporterString.startsWith('z')) {
+      return ZipkinExporter;
+    }
+    if (exporterString.startsWith('j')) {
+      return JaegerExporter;
+    }
+  }
+  return ConsoleSpanExporter;
+})(process.env.EXPORTER);
+
+module.exports = (serviceName) => {
+  const provider = new NodeTracerProvider();
+  registerInstrumentations({
+    tracerProvider: provider,
+    instrumentations: [
+      HttpInstrumentation,
+      RestifyInstrumentation,
+    ],
+  });
+
+  const exporter = new Exporter({
+    serviceName,
+  });
+
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
+  provider.register();
+
+  return opentelemetry.trace.getTracer('restify-example');
+};

plugins/node/opentelemetry-instrumentation-bunyan/.eslintignore

@@ -0,0 +1 @@
+build

plugins/node/opentelemetry-instrumentation-bunyan/.eslintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+    "env": {
+        "mocha": true,
+        "node": true
+    },
+    ...require('../../../eslint.config.js'),
+}

plugins/node/opentelemetry-instrumentation-bunyan/.npmignore

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