docs: fix and update getting-started (#1553)

* docs: fix and update getting-started

* docs: fix and update app.ts

* Fix conflict in ts-example package.json

getting-started/README.md

@@ -22,7 +22,7 @@ This guide will walk you through the setup and configuration process for a traci
 
 This guide assumes you are going to be using Zipkin as your tracing backend, but modifying it for Jaeger should be straightforward.
 
-An example application which can be used with this guide can be found at in the [example directory](example). You can see what it looks like with tracing enabled in the [traced-example directory](traced-example).
+An example application which can be used with this guide can be found in the [example directory](example). You can see what it looks like with tracing enabled in the [traced-example directory](traced-example).
 
 ### Setting up a Tracing Backend
 
@@ -44,7 +44,7 @@ Browse to <http://localhost:9411> to ensure that you can see the Zipkin UI.
 
 ([link to TypeScript version](ts-example/README.md#trace-your-nodejs-application))
 
-This guide uses the example application provided in the `example` directory, but the steps to instrument your own application should be broadly the same. Here is an overview of what we will be doing.
+This guide uses the example application provided in the [example directory](example), but the steps to instrument your own application should be broadly the same. Here is an overview of what we will be doing.
 
 1. Install the required OpenTelemetry libraries
 2. Initialize a global tracer
@@ -169,10 +169,10 @@ Open a command line and `cd` into the directory where you downloaded the Prometh
 $ cd Downloads
 
 $ # Replace the file name below with your downloaded tarball
-$ tar xvfz prometheus-2.14.0.darwin-amd64.tar
+$ tar xvfz prometheus-2.20.1.darwin-amd64.tar
 
 $ # Replace the dir below with your created directory
-$ cd prometheus-2.14.0.darwin-amd64
+$ cd prometheus-2.20.1.darwin-amd64
 
 $ ls
 LICENSE           console_libraries data              prometheus.yml    tsdb
@@ -313,7 +313,7 @@ const exporter = new PrometheusExporter(
   },
   () => {
     console.log(
-      `prometheus scrape endpoint: http://localhost:${prometheusPort}${Prometheusendpoint}`,
+      `prometheus scrape endpoint: http://localhost:${prometheusPort}${prometheusEndpoint}`,
     );
   },
 );

getting-started/monitored-example/monitoring.js

@@ -1,30 +1,33 @@
 "use strict";
-
+ 
 const { MeterProvider } = require('@opentelemetry/metrics');
 const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
-
+ 
+const prometheusPort = PrometheusExporter.DEFAULT_OPTIONS.port
+const prometheusEndpoint = PrometheusExporter.DEFAULT_OPTIONS.endpoint
+ 
 const exporter = new PrometheusExporter(
   {
     startServer: true,
   },
   () => {
     console.log(
-      `prometheus scrape endpoint: http://localhost:${PrometheusExporter.DEFAULT_OPTIONS.port}${PrometheusExporter.DEFAULT_OPTIONS.endpoint}`,
+      `prometheus scrape endpoint: http://localhost:${prometheusPort}${prometheusEndpoint}`,
     );
   },
 );
-
+ 
 const meter = new MeterProvider({
   exporter,
   interval: 1000,
-}).getMeter('example-monitored');
-
+}).getMeter('your-meter-name');
+ 
 const requestCount = meter.createCounter("requests", {
   description: "Count all incoming requests"
 });
-
+ 
 const boundInstruments = new Map();
-
+ 
 module.exports.countAllRequests = () => {
   return (req, res, next) => {
     if (!boundInstruments.has(req.path)) {
@@ -32,8 +35,9 @@ module.exports.countAllRequests = () => {
       const boundCounter = requestCount.bind(labels);
       boundInstruments.set(req.path, boundCounter);
     }
-
+ 
     boundInstruments.get(req.path).add(1);
     next();
   };
 };
+

getting-started/monitored-example/package.json

@@ -10,6 +10,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@opentelemetry/metrics": "^0.11.0",
+    "@opentelemetry/exporter-prometheus": "^0.11.0",
     "axios": "^0.19.0",
     "express": "^4.17.1"
   }

getting-started/traced-example/package.json

@@ -12,7 +12,7 @@
     "@opentelemetry/core": "^0.11.0",
     "@opentelemetry/exporter-zipkin": "^0.11.0",
     "@opentelemetry/node": "^0.11.0",
-    "@opentelemetry/plugin-express": "^0.9.0",
+    "@opentelemetry/plugin-express": "^0.10.0",
     "@opentelemetry/plugin-http": "^0.11.0",
     "@opentelemetry/plugin-https": "^0.11.0",
     "@opentelemetry/tracing": "^0.11.0",

getting-started/ts-example/README.md

@@ -22,7 +22,7 @@ This TypeScript guide will walk you through the setup and configuration process
 
 This guide assumes you are going to be using Zipkin as your tracing backend, but modifying it for Jaeger should be straightforward.
 
-An example application which can be used with this guide can be found at in the same directory.
+An example application which can be used with this guide can be found in the [example directory](example). You can see what it looks like with tracing enabled in the [traced-example directory](traced-example).
 
 ### Setting up a Tracing Backend
 
@@ -44,7 +44,7 @@ Browse to <http://localhost:9411> to ensure that you can see the Zipkin UI.
 
 ([link to JavaScript version](../README.md#trace-your-nodejs-application))
 
-This guide uses the example application provided in the `example` directory, but the steps to instrument your own application should be broadly the same. Here is an overview of what we will be doing.
+This guide uses the example application provided in the [example directory](example) but the steps to instrument your own application should be broadly the same. Here is an overview of what we will be doing.
 
 1. Install the required OpenTelemetry libraries
 2. Initialize a global tracer
@@ -61,7 +61,8 @@ $ npm install \
   @opentelemetry/core \
   @opentelemetry/node \
   @opentelemetry/plugin-http \
-  @opentelemetry/api
+  @opentelemetry/plugin-https \
+  @opentelemetry/plugin-express
 ```
 
 #### Initialize a global tracer
@@ -73,7 +74,6 @@ All tracing initialization should happen before your application’s code runs.
 Create a file named `tracing.ts` and add the following code:
 
 ```typescript
-import * as opentelemetry from '@opentelemetry/api';
 import { LogLevel } from '@opentelemetry/core';
 import { NodeTracerProvider } from '@opentelemetry/node';
 
@@ -170,10 +170,10 @@ Open a command line and `cd` into the directory where you downloaded the Prometh
 $ cd Downloads
 
 $ # Replace the file name below with your downloaded tarball
-$ tar xvfz prometheus-2.14.0.darwin-amd64.tar
+$ tar xvfz prometheus-2.20.1.darwin-amd64.tar
 
 $ # Replace the dir below with your created directory
-$ cd prometheus-2.14.0.darwin-amd64
+$ cd prometheus-2.20.1.darwin-amd64
 
 $ ls
 LICENSE           console_libraries data              prometheus.yml    tsdb
@@ -213,7 +213,7 @@ scrape_configs:
 
 ([link to JavaScript version](../README.md#monitor-your-nodejs-application))
 
-An example application which can be used with this guide can be found at in the current directory.
+An example application which can be used with this guide can be found at in the [example directory](example). You can see what it looks like with metric monitoring enabled in the [monitored-example directory](monitored-example).
 
 1. Install the required OpenTelemetry metrics libraries
 2. Initialize a meter and collect metrics
@@ -342,11 +342,7 @@ export const countAllRequests = () => {
 Ensure prometheus is running by running the `prometheus` binary from earlier and start your application.
 
 ```sh
-$ npm start
-
-> @opentelemetry/getting-started@1.0.0 start /Users/.../opentelemetry-js/getting-started/example/ts
-> ts-node app.ts
-
+$ ts-node app.ts
 prometheus scrape endpoint: http://localhost:9464/metrics
 Listening for requests on http://localhost:8080
 ```

getting-started/ts-example/example/app.ts

@@ -0,0 +1,40 @@
+import * as express from "express";
+import axios from "axios";
+
+const PORT: string = process.env.PORT || "8080";
+
+const app = express();
+
+app.get("/", (req, res) => {
+  axios
+    .get(`http://localhost:${PORT}/middle-tier`)
+    .then(() => axios.get(`http://localhost:${PORT}/middle-tier`))
+    .then(response => {
+      res.send(response.data);
+    })
+    .catch(err => {
+      console.error(err);
+      res.status(500).send();
+    });
+});
+
+app.get("/middle-tier", (req, res) => {
+  axios
+    .get(`http://localhost:${PORT}/backend`)
+    .then(() => axios.get(`http://localhost:${PORT}/backend`))
+    .then(response => {
+      res.send(response.data);
+    })
+    .catch(err => {
+      console.error(err);
+      res.status(500).send();
+    });
+});
+
+app.get("/backend", (req, res) => {
+  res.send("Hello from the backend");
+});
+
+app.listen(parseInt(PORT, 10), () => {
+  console.log(`Listening for requests on http://localhost:${PORT}`);
+});

getting-started/ts-example/example/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@opentelemetry/getting-started-ts-example",
+  "version": "0.11.0",
+  "description": "This repository provides everything required to follow the OpenTelemetry Getting Started Guide",
+  "main": "app.ts",
+  "scripts": {
+    "start": "ts-node app.ts"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/express": "4.17.7",
+    "@types/node": "14.0.27",
+    "ts-node": "8.10.2"
+  },
+  "dependencies": {
+    "axios": "^0.19.1",
+    "express": "^4.17.1"
+  }
+}

getting-started/ts-example/monitored-example/app.ts

@@ -1,11 +1,11 @@
 import * as express from "express";
 import axios from "axios";
 
-import { countAllRequests } from "./monitoring";
-
 const PORT: string = process.env.PORT || "8080";
 
+import { countAllRequests } from './monitoring';
 const app = express();
+app.use(countAllRequests());
 
 app.get("/", (req, res) => {
   axios
@@ -37,8 +37,6 @@ app.get("/backend", (req, res) => {
   res.send("Hello from the backend");
 });
 
-app.use(countAllRequests());
-
 app.listen(parseInt(PORT, 10), () => {
   console.log(`Listening for requests on http://localhost:${PORT}`);
 });

getting-started/ts-example/monitored-example/monitoring.ts

@@ -1,7 +1,9 @@
+import { Request, Response, NextFunction } from 'express';
 import { MeterProvider } from '@opentelemetry/metrics';
-import { Counter } from '@opentelemetry/api';
 import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
-import { RequestHandler } from "express";
+
+const prometheusPort = PrometheusExporter.DEFAULT_OPTIONS.port;
+const prometheusEndpoint = PrometheusExporter.DEFAULT_OPTIONS.endpoint;
 
 const exporter = new PrometheusExporter(
   {
@@ -9,7 +11,7 @@ const exporter = new PrometheusExporter(
   },
   () => {
     console.log(
-      `prometheus scrape endpoint: http://localhost:${PrometheusExporter.DEFAULT_OPTIONS.port}${PrometheusExporter.DEFAULT_OPTIONS.endpoint}`,
+      `prometheus scrape endpoint: http://localhost:${prometheusPort}${prometheusEndpoint}`,
     );
   },
 );
@@ -17,16 +19,16 @@ const exporter = new PrometheusExporter(
 const meter = new MeterProvider({
   exporter,
   interval: 1000,
-}).getMeter('example-ts');
+}).getMeter('your-meter-name');
 
-const requestCount: Counter = meter.createCounter("requests", {
-  description: "Count all incoming requests"
+const requestCount = meter.createCounter('requests', {
+  description: 'Count all incoming requests',
 });
 
 const handles = new Map();
 
-export const countAllRequests = (): RequestHandler => {
-  return (req, res, next) => {
+export const countAllRequests = () => {
+  return (req: Request, _res: Response, next: NextFunction) => {
     if (!handles.has(req.path)) {
       const labels = { route: req.path };
       const handle = requestCount.bind(labels);

getting-started/ts-example/monitored-example/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@opentelemetry/getting-started-monitored-ts-example",
+  "version": "0.11.0",
+  "description": "This repository provides everything required to follow the OpenTelemetry Getting Started Guide",
+  "main": "app.ts",
+  "scripts": {
+    "start": "ts-node app.ts"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/express": "4.17.7",
+    "@types/node": "14.0.27",
+    "ts-node": "8.10.2"
+  },
+  "dependencies": {
+    "@opentelemetry/exporter-prometheus": "^0.11.0",
+    "@opentelemetry/metrics": "^0.11.0",
+    "axios": "^0.19.1",
+    "express": "^4.17.1"
+  }
+}

getting-started/ts-example/traced-example/app.ts

@@ -0,0 +1,40 @@
+import * as express from "express";
+import axios from "axios";
+
+const PORT: string = process.env.PORT || "8080";
+
+const app = express();
+
+app.get("/", (req, res) => {
+  axios
+    .get(`http://localhost:${PORT}/middle-tier`)
+    .then(() => axios.get(`http://localhost:${PORT}/middle-tier`))
+    .then(result => {
+      res.send(result.data);
+    })
+    .catch(err => {
+      console.error(err);
+      res.status(500).send();
+    });
+});
+
+app.get("/middle-tier", (req, res) => {
+  axios
+    .get(`http://localhost:${PORT}/backend`)
+    .then(() => axios.get(`http://localhost:${PORT}/backend`))
+    .then(result => {
+      res.send(result.data);
+    })
+    .catch(err => {
+      console.error(err);
+      res.status(500).send();
+    });
+});
+
+app.get("/backend", (req, res) => {
+  res.send("Hello from the backend");
+});
+
+app.listen(parseInt(PORT, 10), () => {
+  console.log(`Listening for requests on http://localhost:${PORT}`);
+});

getting-started/ts-example/traced-example/package.json

@@ -1,11 +1,10 @@
 {
-  "name": "@opentelemetry/getting-started-ts-example",
+  "name": "@opentelemetry/getting-started-traced-ts-example",
   "version": "0.11.0",
   "description": "This repository provides everything required to follow the OpenTelemetry Getting Started Guide",
   "main": "app.ts",
   "scripts": {
-    "start": "ts-node app.ts",
-    "start-tracing": "ts-node -r ./tracing.ts app.ts"
+    "start": "ts-node app.ts"
   },
   "author": "OpenTelemetry Authors",
   "license": "Apache-2.0",
@@ -15,13 +14,12 @@
     "ts-node": "9.0.0"
   },
   "dependencies": {
-    "@opentelemetry/api": "^0.11.0",
     "@opentelemetry/core": "^0.11.0",
-    "@opentelemetry/exporter-prometheus": "^0.11.0",
     "@opentelemetry/exporter-zipkin": "^0.11.0",
-    "@opentelemetry/metrics": "^0.11.0",
     "@opentelemetry/node": "^0.11.0",
+    "@opentelemetry/plugin-express": "^0.10.0",
     "@opentelemetry/plugin-http": "^0.11.0",
+    "@opentelemetry/plugin-https": "^0.11.0",
     "@opentelemetry/tracing": "^0.11.0",
     "axios": "^0.19.1",
     "express": "^4.17.1"

getting-started/ts-example/traced-example/tracing.ts

@@ -0,0 +1,28 @@
+import { LogLevel } from '@opentelemetry/core';
+import { NodeTracerProvider } from '@opentelemetry/node';
+ 
+import { SimpleSpanProcessor } from '@opentelemetry/tracing';
+import { ZipkinExporter } from '@opentelemetry/exporter-zipkin';
+// For Jaeger, use the following line instead:
+// import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+ 
+const provider: NodeTracerProvider = new NodeTracerProvider({
+  logLevel: LogLevel.ERROR,
+});
+ 
+provider.register();
+ 
+provider.addSpanProcessor(
+  new SimpleSpanProcessor(
+    new ZipkinExporter({
+      // For Jaeger, use the following line instead:
+      // new JaegerExporter({
+      serviceName: 'getting-started',
+      // If you are running your tracing backend on another host,
+      // you can point to it using the `url` parameter of the
+      // exporter config.
+    }),
+  ),
+);
+ 
+console.log('tracing initialized');

getting-started/ts-example/tracing.ts

@@ -1,23 +0,0 @@
-import { LogLevel } from '@opentelemetry/core';
-import { NodeTracerProvider } from "@opentelemetry/node";
-import { SimpleSpanProcessor } from "@opentelemetry/tracing";
-import { ZipkinExporter } from "@opentelemetry/exporter-zipkin";
-
-const provider: NodeTracerProvider = new NodeTracerProvider({
-  logLevel: LogLevel.ERROR
-});
-
-provider.register();
-
-provider.addSpanProcessor(
-  new SimpleSpanProcessor(
-    new ZipkinExporter({
-      serviceName: "getting-started"
-      // If you are running your tracing backend on another host,
-      // you can point to it using the `url` parameter of the
-      // exporter config.
-    })
-  )
-);
-
-console.log("tracing initialized");