Add gRPC integration guide

examples/grpc/README.md

@@ -0,0 +1,38 @@
+# Overview
+
+Our service takes in a payload containing bytes and capitalizes them.
+
+Using OpenCensus Node, we can collect traces of our system and export them to the backend of our choice, to give observability to our distributed systems.
+
+
+## Installation
+
+```sh
+$ # from this directory
+$ npm install
+```
+
+
+## Run the Application
+
+ - Run the server
+
+   ```sh
+   $ # from this directory
+   $ node ./capitalize_server.js
+   ```
+
+ - Run the client
+
+   ```sh
+   $ # from this directory
+   $ node ./capitalize_client.js
+   ```
+
+## Useful links
+- For more information on OpenCensus, visit: <https://opencensus.io/>
+- To checkout the OpenCensus for Node.js, visit: <https://github.com/census-instrumentation/opencensus-node>
+
+## LICENSE
+
+Apache License 2.0

examples/grpc/capitalize_client.js

@@ -0,0 +1,95 @@
+/**
+ * Copyright 2019, OpenCensus 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
+ *
+ *      gRPC://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 path = require('path');
+const grpc = require('grpc');
+const protoLoader = require('@grpc/proto-loader');
+const tracing = require('@opencensus/nodejs');
+const { plugin } = require('@opencensus/instrumentation-grpc');
+const { StackdriverTraceExporter } =
+    require('@opencensus/exporter-stackdriver');
+
+let tracer;
+
+setupOpencensusAndExporters();
+
+const PROTO_PATH = path.join(__dirname, 'protos/defs.proto');
+const PROTO_OPTIONS = { keepCase: true, enums: String, defaults: true, oneofs: true };
+const definition = protoLoader.loadSync(PROTO_PATH, PROTO_OPTIONS);
+const rpcProto = grpc.loadPackageDefinition(definition).rpc;
+
+function main () {
+  const client = new rpcProto.Fetch('localhost:50051',
+    grpc.credentials.createInsecure());
+  let data;
+  if (process.argv.length >= 3) {
+    data = process.argv[2];
+  } else {
+    data = 'opencensus';
+  }
+  console.log('> ', data);
+
+  tracer.startRootSpan({ name: 'octutorialsClient.capitalize' }, rootSpan => {
+    client.capitalize({ data: Buffer.from(data) }, function (err, response) {
+      if (err) {
+        console.log('could not get grpc response');
+        return;
+      }
+      console.log('< ', response.data.toString('utf8'));
+      rootSpan.end();
+    });
+  });
+
+  setTimeout(() => {
+    console.log('done.');
+  }, 60000);
+}
+
+function setupOpencensusAndExporters () {
+  // Enable OpenCensus exporters to export traces to Stackdriver CloudTrace.
+  // Exporters use Application Default Credentials (ADCs) to authenticate.
+  // See https://developers.google.com/identity/protocols/application-default-credentials
+  // for more details.
+  // Expects ADCs to be provided through the environment as ${GOOGLE_APPLICATION_CREDENTIALS}
+  // A Stackdriver workspace is required and provided through the environment as ${GOOGLE_PROJECT_ID}
+  const projectId = process.env.GOOGLE_PROJECT_ID;
+
+  // GOOGLE_APPLICATION_CREDENTIALS are expected by a dependency of this code
+  // Not this code itself. Checking for existence here but not retaining (as not needed)
+  if (!projectId || !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    throw Error('Unable to proceed without a Project ID');
+  }
+
+  // Creates Stackdriver exporter
+  const exporter = new StackdriverTraceExporter({ projectId: projectId });
+
+  // Starts Stackdriver exporter
+  tracing.registerExporter(exporter).start();
+
+  // Starts tracing and set sampling rate
+  tracer = tracing.start({
+    samplingRate: 1 // For demo purposes, always sample
+  }).tracer;
+
+  // Defines basedir and version
+  const basedir = path.dirname(require.resolve('grpc'));
+  const version = require(path.join(basedir, 'package.json')).version;
+
+  // Enables GRPC plugin: Method that enables the instrumentation patch.
+  plugin.enable(grpc, tracer, version, /** plugin options */{}, basedir);
+}
+
+main();

examples/grpc/capitalize_server.js

@@ -0,0 +1,88 @@
+/**
+ * Copyright 2019, OpenCensus 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
+ *
+ *      gRPC://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 path = require('path');
+const grpc = require('grpc');
+const protoLoader = require('@grpc/proto-loader');
+const tracing = require('@opencensus/nodejs');
+const { plugin } = require('@opencensus/instrumentation-grpc');
+const { StackdriverTraceExporter } =
+    require('@opencensus/exporter-stackdriver');
+
+let tracer;
+
+setupOpencensusAndExporters();
+
+const PROTO_PATH = path.join(__dirname, 'protos/defs.proto');
+const PROTO_OPTIONS = { keepCase: true, enums: String, defaults: true, oneofs: true };
+const definition = protoLoader.loadSync(PROTO_PATH, PROTO_OPTIONS);
+const rpcProto = grpc.loadPackageDefinition(definition).rpc;
+
+/** Implements the Capitalize RPC method. */
+function capitalize (call, callback) {
+  const span = tracer.startChildSpan('octutorials.FetchImpl.capitalize');
+  const data = call.request.data.toString('utf8');
+  const capitalized = data.toUpperCase();
+  for (let i = 0; i < 100000000; i++) {}
+  span.end();
+  callback(null, { data: Buffer.from(capitalized) });
+}
+
+/**
+ * Starts an RPC server that receives requests for the Fetch service at the
+ * sample server port.
+ */
+function main () {
+  const server = new grpc.Server();
+  server.addService(rpcProto.Fetch.service, { capitalize: capitalize });
+  server.bind('0.0.0.0:50051', grpc.ServerCredentials.createInsecure());
+  server.start();
+}
+
+function setupOpencensusAndExporters () {
+  // Enable OpenCensus exporters to export traces to Stackdriver CloudTrace.
+  // Exporters use Application Default Credentials (ADCs) to authenticate.
+  // See https://developers.google.com/identity/protocols/application-default-credentials
+  // for more details.
+  // Expects ADCs to be provided through the environment as ${GOOGLE_APPLICATION_CREDENTIALS}
+  // A Stackdriver workspace is required and provided through the environment as ${GOOGLE_PROJECT_ID}
+  const projectId = process.env.GOOGLE_PROJECT_ID;
+
+  // GOOGLE_APPLICATION_CREDENTIALS are expected by a dependency of this code
+  // Not this code itself. Checking for existence here but not retaining (as not needed)
+  if (!projectId || !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    throw Error('Unable to proceed without a Project ID');
+  }
+  // Creates Stackdriver exporter
+  const exporter = new StackdriverTraceExporter({ projectId: projectId });
+
+  // Starts Stackdriver exporter
+  tracing.registerExporter(exporter).start();
+
+  // Starts tracing and set sampling rate
+  tracer = tracing.start({
+    samplingRate: 1 // For demo purposes, always sample
+  }).tracer;
+
+  // Defines basedir and version
+  const basedir = path.dirname(require.resolve('grpc'));
+  const version = require(path.join(basedir, 'package.json')).version;
+
+  // Enables GRPC plugin: Method that enables the instrumentation patch.
+  plugin.enable(grpc, tracer, version, /** plugin options */{}, basedir);
+}
+
+main();

examples/grpc/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "grpc-example",
+  "version": "0.0.1",
+  "description": "Example of gRPC integration with OpenCensus",
+  "repository": "census-instrumentation/opencensus-node",
+  "keywords": [
+    "opencensus",
+    "grpc",
+    "tracing",
+    "stats",
+    "metrics"
+  ],
+  "author": "OpenCensus Authors",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=6.0"
+  },
+  "scripts": {
+    "lint": "semistandard *.js",
+    "fix": "semistandard --fix"
+  },
+  "dependencies": {
+    "@grpc/proto-loader": "^0.4.0",
+    "@opencensus/exporter-stackdriver": "^0.0.9",
+    "@opencensus/instrumentation-grpc": "^0.0.9",
+    "@opencensus/nodejs": "^0.0.9",
+    "grpc": "^1.18.0"
+  },
+  "devDependencies": {
+    "semistandard": "^13.0.1"
+  }
+}

examples/grpc/protos/defs.proto

@@ -0,0 +1,33 @@
+// Copyright 2019, OpenCensus 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.
+
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "io.grpc.examples.helloworld";
+option java_outer_classname = "HelloWorldProto";
+option objc_class_prefix = "HLW";
+
+package rpc;
+
+service Fetch {
+  // Sends a capitalizes payload
+  rpc Capitalize(Payload) returns (Payload) {}
+}
+
+// The request and response payload containing the id and data.
+message Payload {
+  int32 id    = 1;
+  bytes data  = 2;
+}