feat(tracing): add Jaeger for easier OpenTracing

Adds a command line flag and docs to easily set up a Jaeger instance for
debugging performance issues.

Author: felixfbecker

README.md

@@ -69,6 +69,7 @@ npm test
     -c, --cluster [num]   number of concurrent cluster workers (defaults to number of CPUs, 8)
     -t, --trace           print all requests and responses
     -l, --logfile [file]  log to this file
+    -j, --enable-jaeger   enable OpenTracing through Jaeger
 ```
 
 ## Extensions
@@ -90,3 +91,18 @@ This language server implements some LSP extensions, prefixed with an `x`.
 
 This project follows [semver](http://semver.org/) for command line arguments and standard LSP methods.
 Any change to command line arguments, Node version or protocol breaking changes will result in a major version increase.
+
+## Debugging Performance with OpenTracing
+
+The language server is fully traced through [OpenTracing](http://opentracing.io/), which allows to debug what exact operations caused method calls to take long.
+You can pass a span context through an optional `meta` field on the JSON RPC message object.
+
+For local development, there is built-in support for the open source OpenTracing implementation [Jaeger](http://jaeger.readthedocs.io/en/latest/), which can be set up to run on localhost with just one command (you need [Docker](https://www.docker.com/) installed):
+
+```
+docker run -d -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp \
+  -p5778:5778 -p16686:16686 -p14268:14268 jaegertracing/all-in-one:latest
+```
+
+After that, run the language server with the `--enable-jaeger` command line flag and do some requests from your client.
+Open http://localhost:16686 in your browser and you will see method calls broken down into spans.

package.json

@@ -43,6 +43,7 @@
     "fast-json-patch": "^2.0.2",
     "glob": "^7.1.1",
     "iterare": "^0.0.8",
+    "jaeger-client": "^3.5.3",
     "lodash": "^4.17.4",
     "mz": "^2.6.0",
     "object-hash": "^1.1.8",

src/connection.ts

@@ -2,7 +2,7 @@ import { Observable, Subscription, Symbol } from '@reactivex/rxjs';
 import { EventEmitter } from 'events';
 import { applyReducer, Operation } from 'fast-json-patch';
 import { camelCase, omit } from 'lodash';
-import { FORMAT_TEXT_MAP, Span, Tracer } from 'opentracing';
+import { FORMAT_TEXT_MAP, SpanContext, Tracer } from 'opentracing';
 import { inspect } from 'util';
 import { ErrorCodes, Message, StreamMessageReader as VSCodeStreamMessageReader, StreamMessageWriter as VSCodeStreamMessageWriter } from 'vscode-jsonrpc';
 import { isNotificationMessage, isRequestMessage, isResponseMessage, NotificationMessage, RequestMessage, ResponseMessage } from 'vscode-jsonrpc/lib/messages';
@@ -210,17 +210,13 @@ export function registerLanguageHandler(messageEmitter: MessageEmitter, messageW
 				return;
 		}
 		const method = camelCase(message.method);
-		let span = new Span();
-		if (isRequestMessage(message)) {
-			// If message is request and has tracing metadata, extract the span context and create a span for the method call
-			if (hasMeta(message)) {
-				const context = tracer.extract(FORMAT_TEXT_MAP, message.meta);
-				if (context) {
-					span = tracer.startSpan('Handle ' + message.method, { childOf: context });
-					span.setTag('params', inspect(message.params));
-				}
-			}
+		let context: SpanContext | undefined;
+		// If message is request and has tracing metadata, extract the span context
+		if (isRequestMessage(message) && hasMeta(message)) {
+			context = tracer.extract(FORMAT_TEXT_MAP, message.meta) || undefined;
 		}
+		const span = tracer.startSpan('Handle ' + message.method, { childOf: context });
+		span.setTag('params', inspect(message.params));
 		if (typeof (handler as any)[method] !== 'function') {
 			// Method not implemented
 			if (isRequestMessage(message)) {

src/language-server-stdio.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { Tracer } from 'opentracing';
 import { isNotificationMessage } from 'vscode-jsonrpc/lib/messages';
 import { MessageEmitter, MessageLogOptions, MessageWriter, registerLanguageHandler, RegisterLanguageHandlerOptions } from './connection';
 import { RemoteLanguageClient } from './lang-handler';
@@ -8,19 +9,24 @@ import { TypeScriptService, TypeScriptServiceOptions } from './typescript-servic
 
 const packageJson = require('../package.json');
 const program = require('commander');
+const { initTracer } = require('jaeger-client');
 
 program
 	.version(packageJson.version)
 	.option('-s, --strict', 'enables strict mode')
 	.option('-t, --trace', 'print all requests and responses')
 	.option('-l, --logfile [file]', 'log to this file')
+	.option('-j, --enable-jaeger', 'enable OpenTracing through Jaeger')
 	.parse(process.argv);
 
 const logger = program.logfile ? new FileLogger(program.logfile) : new StderrLogger();
+const tracer = program.enableJaeger ? initTracer({ serviceName: 'javascript-typescript-langserver', sampler: { type: 'const', param: 1 } }) : new Tracer();
+
 const options: TypeScriptServiceOptions & MessageLogOptions & RegisterLanguageHandlerOptions = {
 	strict: program.strict,
 	logMessages: program.trace,
-	logger
+	logger,
+	tracer
 };
 
 const messageEmitter = new MessageEmitter(process.stdin, options);

src/language-server.ts

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
+import { Tracer } from 'opentracing';
 import { FileLogger, StdioLogger } from './logging';
 import { serve, ServeOptions } from './server';
 import { TypeScriptService, TypeScriptServiceOptions } from './typescript-service';
 const program = require('commander');
 const packageJson = require('../package.json');
+const { initTracer } = require('jaeger-client');
 
 const defaultLspPort = 2089;
 const numCPUs = require('os').cpus().length;
@@ -16,14 +18,16 @@ program
 	.option('-c, --cluster [num]', 'number of concurrent cluster workers (defaults to number of CPUs, ' + numCPUs + ')', parseInt)
 	.option('-t, --trace', 'print all requests and responses')
 	.option('-l, --logfile [file]', 'log to this file')
+	.option('-j, --enable-jaeger', 'enable OpenTracing through Jaeger')
 	.parse(process.argv);
 
 const options: ServeOptions & TypeScriptServiceOptions = {
 	clusterSize: program.cluster || numCPUs,
 	lspPort: program.port || defaultLspPort,
 	strict: program.strict,
 	logMessages: program.trace,
-	logger: program.logfile ? new FileLogger(program.logfile) : new StdioLogger()
+	logger: program.logfile ? new FileLogger(program.logfile) : new StdioLogger(),
+	tracer: program.enableJaeger ? initTracer({ serviceName: 'javascript-typescript-langserver', sampler: { type: 'const', param: 1 } }) : new Tracer()
 };
 
 serve(options, client => new TypeScriptService(client, options));