angular-tracing v0.0.2
angular-tracing
Distributed tracing for Angular applications.
Note: This library is currently a heavy work in progress so expect there to be breaking changes.
Goals
- Enable distributed tracing for Angular applications
- Support for tracing in both components and views
- Tracing integration for Angular's HttpClient
- Tracing library independent (without providing leaky abstractions)
Demo
- Download the repo
- Run
yarn quick
(requires Docker to be installed) - Open http://localhost:4200 and click through some page
- Open the Zipkin UI at http://localhost:9411 and view the traces
You can view the source of the example Angular application being traced under apps/heroes-villains
.
Usage
Configuration
To get started, Add the tracing module to your app.module
:
@NgModule({
declarations: [...],
imports: [
...
ZipkinModule.forRoot({
traceProvider: {
http: {
remoteServiceMapping: {
all: /.*/
}
},
logToConsole: true
}
})
],
providers: [],
bootstrap: [...]
})
export class AppModule {}
The remoteServiceMapping
element maps outbound HTTP requests to a backend service. In the above example, we have white listed all outbound requests via a regular expression to map to the service name all
. In your application, you will likely have one or more backend services that are being traced that your application will make requests to. A more realistic real world configuration:
const function remoteServiceMappings() {
const mappings = {};
mappings['api_server'] = Environment.API_SERVER;
mappings['github'] = 'api.github.com';
mappings['mapbpx'] = /.*mapbox.com.*/
}
{
remoteServiceMapping: remoteServiceMappings()
}
The default configuration will setup tracing of the HttpClient
and send to a remote Zipkin service operating at https://localhost:9411
. For additional configuration options, please see the core and zipkin configuration definitions.
Components
Typical tracing in a component might look soemthing like this:
@Component({
selector: 'app-heroes',
templateUrl: './heroes.component.html'
})
export class HeroesComponent implements OnInit, AfterViewInit {
heroes$: Observable<Hero[]>;
private tracer: LocalTracer;
constructor(private heroService: HeroService, private user: User, traceRoot: ZipkinTraceRoot) {
this.heroes$ = heroService.entities$;
this.localTracer = traceRoot.localTracer();
}
ngOnInit() {
this.localTracer.startSpan('heroesComponent');
this.getHeroes();
try {
this.localTracer.startSpan('expensive_history_recording_call');
this.localTracer.setTags({ user: user.id });
this.user.recordHistory();
finally {
this.localTracer.endSpan();
}
}
ngAfterViewInit(): void {
this.localTracer.endSpan();
}
}
Let's walk through the different pieces:
- The
ZipkinTraceRoot
is a locator for finding the root span. Inzipkin-js
, the root span is created by creating aTracer
instance. - The
LocalTracer
is an adapter for runnning Zipkin traces in a synchronous context. Zipkin'sTracer
class provides a method for doing local traces via a callback pattern. - The
startSpan
andendSpan
methods used inngOnInit
andngAfterViewInit
will open a close a span so that anything that happens during that span's creation is included in that span. - The child span created for
expensive_history_recording_call
will exist as a child of theheroesComponent
call and a tag ofuser
with the user's ID.
What would happen if we didn't open a span for the Heroes component? By default, the Httpclient
alls made getHeroes
would be traced but not in the context of a specific span (only in the context of the default application). You can change the configuration so that HTTP calls are not traced unless there is an existing root span.
Directives
You can also enable tracing with your component by using directives. Any element can by traced, but let's assume that we are rendering a user:
<app-user-component [id]="user.id"></app-user-component>
To add tracing to the component, you add the trace
directive:
<app-user-component trace [id]="user.id"></app-user-component>
This will start a span for the rendering of the component. You can add a specific name for the span:
<app-user-component trace [traceName]="'userComponent'" [id]="user.id"></app-user-component>
And add tags:
<app-user-component
trace
[traceName]="'userComponent'"
[traceTags]="{ user: user.id }"
[id]="user.id"
></app-user-component>
Or log a message:
<app-user-component
trace
[traceName]="'userComponent'"
[traceTags]="{ user: user.id }"
[traceMessage]="'Rendering a user as part of the UserHistory component'"
[id]="user.id"
></app-user-component>
Tracing Libraries
There are a number of tracing libraries available including:
- Zipkin
- OpenCensus (no browser compatible library at the moment)
- OpenTracing
This library currently only has an implementation for sending traces to Zipkin, but the intent is not to be opinated on which tracing library you use. However, this library is opinionated in the fact that the underlying tracing system should be directly exposed to the user (i.e. we are not going to provide a leaky abstraction over all distributed tracing systems). You'll notice in the examples above the all of the code directly references Zipkin's Tracer
class. The only abstraction provided is
root span locator - which is necessary in a single page web application.
Development
- This repository is a nx / Angular CLI based repository
- The easiest way to develop is by running the end to end example using
yarn quick
. - Tests are run via
karma
by runningyarn test
Please see the open issues in the repo for discussion on bugs/enhancements.
5 years ago