This package has been deprecated

Author message:

Package no longer supported. Contact Support at for more info.

TypeScript icon, indicating that this package has built-in type declarations

0.6.0 • Public • Published


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.


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

  // ...


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


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(/* ... */);


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


  • 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: 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,


  • 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(),


  • 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.
      type: 'custom',
      values: {
        my_custom_metric: Math.random(),
        type: 'custom',
        values: {
          my_custom_metric: Math.random(),
        span: mySpan,


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']);

  instrumentations: [new MyInstrumentation()],


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';

  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 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

  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';




Package Sidebar


Weekly Downloads






Unpacked Size

424 kB

Total Files


Last publish


  • teodosii
  • yulia.shanyrova
  • clord
  • reemtariqq
  • grafanabot
  • scottleppgrafana
  • academo_grafana
  • jwestbrook
  • ivanahuckova
  • domasx2
  • bmatei
  • dsotirakis
  • tolzhabayev
  • iwysiu
  • andresmgotor
  • leventebalogh
  • torkelo
  • dprokop
  • peteholmberg
  • ryantxu
  • mckn
  • sunker