@grafana/agent-core

DEPRECATED Project has been moved to @grafana/faro-core

Core package of Grafana JavaScript Agent.

Warning: currently pre-release and subject to frequent breaking changes. Use at your own risk.

The entire architecture of the library is contained within this package. Out of the box, it doesn't collect any metrics, logs etc. but it offers an API to capture them.

Installation

import { initializeGrafanaAgent } from '@grafana/agent-core';

initializeGrafanaAgent({
  // ...
});

Options

The agent requires a configuration parameter with the following properties:

Property	Description	Type	Default Value Variable
`app`	Application metadata	`App`
`dedupe`	A flag for toggling deduplication filter	`boolean`
`globalObjectKey`	String that should be used when defining the agent on the global object	`string`	`defaultGlobalObjectKey = 'grafanaAgent'`
`instrumentations`	Array of instrumentations that should be ran	`Instrumentation[]`
`internalLoggerLevel`	The level of information printed to console for internal messages	`InternalLoggerLevel`	`defaultInternalLoggerLevel = InternalLoggerLevel.ERROR`
`isolate`	A flag that will create an isolated agent	`boolean`
`metas`	Array of metas that should be logged	`MetaItem[]`
`parseStacktrace`	A function used to parse stack traces	`StacktraceParser`
`paused`	Flag for initializing the agent as paused	`boolean`
`preventGlobalExposure`	Flag for toggling the definition on the global object	`boolean`
`transports`	Array of transports that should be used	`Transport[]`

Besides the mandatory properties, the agent also supports the following optional properties:

Property	Description	Type	Default Value
`beforeSend`	Hook invoked before pushing event to transport. Can be used to modify or filter events	`BeforeSendHook`	`undefined`
`eventDomain`	event.domain attribute of an event, to be set on every event item as default	`string`	`undefined`
`ignoreErrors`	Error message patterns for errors that should be ignored	`Patterns`	`[]`
`session`	Session metadata	`Session`	`undefined`
`user`	User metadata	`User`	`undefined`

Agent

The agent is an object which can be accessed by either importing it from the package or by referencing it from the global object (window in browsers and global in Node.js).

// Browser/Node.js
import { agent } from '@grafana/agent-core';

agent.api.pushLog(/* ... */);

// Browser
window.grafanaAgent.api.pushLog(/* ... */);

// Node.js
global.grafanaAgent.api.pushLog(/* ... */);

API

The api property on the agent contains all the necessary methods to push new events.

Errors

pushError - is a method to push an error/exception to the agent. It accepts a mandatory message parameter and an optional one where you can set:

skipDedupe - a flag for enforcing event push even if the event is identical to the previous one.
stackFrames - an array of stack frames. Defaults to parsing error.stack if present.
type - the type of exception. Default value: error.name or "error".

agent.api.pushError(new Error('This is an error'));

agent.api.pushError(new Error('This is an unhandled exception'), { type: 'unhandledException' });

agent.api.pushError(new Error('This is an error with stack frames'), {
  stackFrames: [
    {
      filename: 'file.js',
      function: 'myFunction',
      colno: 120,
      lineno: 80,
    },
  ],
});

Logs

pushLog - is a method to register a log event. The method accepts a mandatory args parameter which is an array of arguments that will be stringified and send to the transports. The other two parameters are optional: logLevel is the type of message that we register and context is a plain object containing primitive values that will be recorded along with the message.
```
agent.api.pushLog(['This is a log', 'With another message']);

agent.api.pushLog(['This is a warning'], { level: LogLevel.WARN });

agent.api.pushLog(['This is a log with context'], {
  context: {
    randomNumber: Math.random(),
  },
});
```

Measurements

pushMeasurement - is a method for registering metrics. The method accepts a mandatory payload parameter and an optional parameter for passing additional options:

span - the span where the exception has occurred. Default value: undefined.

agent.api.pushMeasurement({
  type: 'custom',
  values: {
    my_custom_metric: Math.random(),
  },
});

agent.api.pushMeasurement(
  {
    type: 'custom',
    values: {
      my_custom_metric: Math.random(),
    },
  },
  {
    span: mySpan,
  }
);

Instrumentations

Instrumentations are packages that leverage the agent API to provide automatic mechanisms for collecting data. They are just simple functions that are executed when the agent is initialized.

Please note that the core package does not contain any instrumentations out of the box and they should be provided by platform specific packages like @grafana/agent-web

You can also write your own instrumentations:

import { agent, initializeGrafanaAgent, BaseInstrumentation } from '@grafana/agent-core';

export class MyInstrumentation extends BaseInstrumentation {
  readonly version = '1.0.0';
  readonly name = 'my-instrumentation';

  initialize(): void {
    this.agent.api.pushLog(['hello from my instrumentation']);
  }
}

initializeGrafanaAgent({
  instrumentations: [new MyInstrumentation()],
});

Metas

Metas are objects that will be attached to every event that is triggered by the API.

Out of the box, only one meta is provided: sdk which contains information about the agent and its version. Additional metas can be provided by external packages like @grafana/agent-meta-browser and @grafana/agent-meta-page.

You can also define your own metas:

import { agent, initializeGrafanaAgent } from '@grafana/agent-core';

initializeGrafanaAgent({
  metas: [
    // Define a static meta
    {
      app: {
        name: 'my-app',
        version: '1.0.0',
      },
    },

    // Define a meta which caches some values on initialization
    () => {
      return {
        user: {
          username: getUser().name,
        },
      };
    },
  ],
});

Transports

Transports are functions that will be called for every event that is triggered by the API. They are used to do something with the data after collecting it.

Out of the box, no transports are provided in the core package and they should be provided by platform specific packages like @grafana/agent-web

You can also define your own transports:

import { agent, initializeGrafanaAgent, BaseTransport, TransportItem } from '@grafana/agent-core';

class MyTransport extends BaseTransport {
  send(item: TransportItem) {
    // do something with paylaod
  }
}

initializeGrafanaAgent({
  transports: [new MyTransport()],
});

Unpatched console

Some instrumentations might override the default console methods but the agent provides a way to access the unmodified console methods.

agent.unpatchedConsole.log('This is a log');
agent.unpatchedConsole.warn('This is a warning');

Pause / unpause

Agent can be paused by invoking agent.pause(). This will prevent events from being sent to transports. Call agent.unpause() to resume capturing events.

Isolated agents

Sometimes you may want to create one or more isolated agents. For example:

you want to bundle the agent in a reusable library and report certain events only for it while the project where the library is used has its own agent
you want to log certain events in one system while other events in other systems
E2E libraries that may create multiple agents without refreshing the page

In order to achieve this, you can use the isolate flag when initializing the agent:

// agent 1 will be isolated
const agent1 = initializeGrafanaAgent({
  // ...
  isolate: true,
});

// globalAgent will be available globally
const globalAgent = initializeGrafanaAgent({
  // ...
  isolate: true,
});

// another isolated agent
const agent2 = initializeGrafanaAgent({
  // ...
  isolate: true,
});

Although an isolated agent may sound like a great idea, there are some limitations which apply to them:

some instrumentations will still register globally (i.e. exceptions instrumentation or console instrumentation)
an isolated agent will not be available on the global object
the agent reference should be stored by the project as it won't be available via import { agent } from '@grafana/agent-core';