OpenTelemetry

• External Mode
• Internal Mode

Graphweaver comes with OpenTelemetry support built in. This means that you can see traces of requests as they come in to the GraphQL server.

By default OpenTelemetry is disabled, this guide will help you configure it for your app.

To start there are two modes supported, external or internal mode.

External mode sends all trace requests to an external OpenTelemetry collector. This is the best mode for running in production as the processing of traces is handled by a secondary process and can be stored in a tracing platform such as https://www.jaegertracing.io/ or a hosted platform like https://signoz.io/.

Integrated mode shows traces within the AdminUI and sends trace data to a data provider of your choice. This mode is quick to enable and see results and does not rely on any external services. However, trace processing is handled in the same thread as your app logic and this will slow down performance.

Let’s look at how to implement both modes in detail next.

External Mode

This mode is best for a production instance of Graphweaver as all trace processing will happen in an external process improving the performance of Graphweaver.

To configure Graphweaver to send all trace data to an external collector you can configure two env vars. OTEL_EXPORTER_OTLP_ENDPOINT - The endpoint of the collector

OTEL_EXPORTER_OTLP_HEADERS - (Optional) Any HTTP headers that you need to send to the collector.

Let’s look at an example and send data from Graphweaver to a hosted platform like Signoz.

Here is how you would configure the env vars to send the trace data to the Signoz platform:

OTEL_EXPORTER_OTLP_HEADERS="signoz-access-token={ENTER_API_KEY_HERE}"
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.us.signoz.cloud:443"

Graphweaver will then start sending all traces to this endpoint.

You can also setup Graphweaver to send to a local Open Telemetry Collector:

https://signoz.io/blog/opentelemetry-collector-complete-guide/

This is a great option to improve performance as the request to the collector is local and the latency is as low as possible. The Open Telemetry Collector can then forward the traces on to your platform.

Internal Mode

The second option is to store the trace data within a connected data provider. These means that you can store traces in a Postgres, MySQL or SQLite connected datasource.

Let’s look at how to enable it on a SQLite project.

First, we need to create a data entity to store the trace data. This will need to implement the properties that are found in the TraceData type:

import { Entity, PrimaryKey, Property, JsonType, BigIntType } from '@mikro-orm/core';
import { TraceData } from '@exogee/graphweaver';

@Entity({ tableName: 'Trace' })
export class Trace implements TraceData {
	@PrimaryKey({ fieldName: 'Id', type: new BigIntType('string') })
	id!: string;

	@Property({ fieldName: 'SpanId', type: String })
	spanId!: string;

	@Property({ fieldName: 'TraceId', type: String })
	traceId!: string;

	@Property({ fieldName: 'ParentId', type: String })
	parentId!: string;

	@Property({ fieldName: 'Name', type: 'NVARCHAR(200)' })
	name!: string;

	@Property({ fieldName: 'Timestamp', type: new BigIntType('bigint') })
	timestamp!: bigint;

	@Property({ fieldName: 'Duration', type: new BigIntType('bigint') })
	duration!: bigint;

	@Property({ fieldName: 'Attributes', type: JsonType })
	attributes!: Record<string, unknown>;
}

Then you need to connect the data entity to the database connection:

export const traceConnection = {
	connectionManagerId: 'sqlite',
	mikroOrmConfig: {
		entities: [Trace],
		driver: SqliteDriver,
		dbName: 'databases/trace.sqlite',
	},
};

Next, you will need to create an SQLite database with the following schema:

CREATE TABLE [Trace]
(
    [Id] INTEGER NOT NULL,
    [SpanId] NVARCHAR(200) NOT NULL,
    [TraceId] NVARCHAR(200) NOT NULL,
    [ParentId] NVARCHAR(200),
    [Name] NVARCHAR(200) NOT NULL,
    [Timestamp] BIGINT NOT NULL,
    [Duration] BIGINT NOT NULL,
    [Attributes] JSON,
    CONSTRAINT [PK_Track] PRIMARY KEY ([Id])
);

Finally, you need to connect the data entity to a data provider and tell Graphweaver to use this for storing traces:

import { Trace } from './entities';

// Create a trace data provider used to fetch the data
export const traceProvider = new MikroBackendProvider(Trace, traceConnection);

export const graphweaver = new Graphweaver({
  // Configure Open Telemetry to use the traceProvider 
	openTelemetry: {
		traceProvider,
	},
});

Once you have this setup you can start Graphweaver and view traces in the Analytics view:

If you have applied 🔏Authentication to your project then instead of seeing this view, you will receive a Forbidden error on this page. By default Graphweaver blocks access to entities that have no Access Control List defined. You can define an Access Control List for the built in Trace entity as follows:

import { TraceData, Trace as TraceGraphQLEntity } from '@exogee/graphweaver';
import { ApplyAccessControlList } from '@exogee/graphweaver-auth';
import { BigIntType, Entity, JsonType, PrimaryKey, Property } from '@mikro-orm/core';
import { Roles } from '../../auth';

ApplyAccessControlList({
	[Roles.ADMIN]: { read: true },
	[Roles.SUPER_ADMIN]: { read: true },
})(TraceGraphQLEntity);

@Entity({ tableName: 'Trace' })
export class Trace implements TraceData {
	@PrimaryKey({ fieldName: 'Id', type: new BigIntType('string') })
	id!: string;

	@Property({ fieldName: 'SpanId', type: String })
	spanId!: string;

	@Property({ fieldName: 'TraceId', type: String })
	traceId!: string;

	@Property({ fieldName: 'ParentId', type: String })
	parentId!: string;

	@Property({ fieldName: 'Name', type: 'NVARCHAR(200)' })
	name!: string;

	@Property({ fieldName: 'Timestamp', type: new BigIntType('bigint') })
	timestamp!: bigint;

	@Property({ fieldName: 'Duration', type: new BigIntType('bigint') })
	duration!: bigint;

	@Property({ fieldName: 'Attributes', type: JsonType })
	attributes!: Record<string, unknown>;
}

You could choose for example to allow Admins to only see certain types of traces, etc. This works the same as other Access Control Lists in Graphweaver.

For a complete example of tracing working locally see the https://github.com/exogee-technology/graphweaver/tree/main/src/examples/sqlite example.