Frontend tracing - NEW!

Frontend instrumentation is in its early stages. If you encounter any issues contact support.

Configuration is required.

Sprkl frontend instrumentation provides function-level instrumentation to every code change. The frontend trace will show you every click and HTTP request made, connecting it to the related source code, and propagating the context to your backend.

User click on checkout trace

Sprkl and OpenTelemetry instrumentation can be enabled on the frontend by doing the following:

1. Instrument your web server code with the Sprkl CLI in any environment.

2. Transpiler plugin - either Webpack or Rollup.

Configuration

Webpack

1. Install the Webpack loader:

npm install --save-dev @sprkl/obs-webpack-loader

2. Configure Webpack

Webpack configuration is also available for:

• Next.js

• Webpack Dev Server

const sprklOptions = {}
module.exports = {
  module: {
    rules: [
      {
        use: [
          { loader: '@sprkl/obs-webpack-loader', options: sprklOptions},
        ],
      },
    ],
  },
};

Rollup

1. Install the Rollup plugin:

npm install --save-dev @sprkl/obs-rollup-plugin

2. Configure Rollup

Rollup configuration is also available for:

• Vite

import sprkl from '@sprkl/obs-rollup-plugin'
const sprklOptions = {}
export default (async () => ({
  plugins: [sprkl(sprklOptions)],
}))();

Transpiler configuration Options

These options are used both for the Webpack loader and the Rollup plugin.

export type Options = {
  /**
   When enabled, the modes in which sprkl operates.
   Mode is either 'development' or 'production'.
   In rollup mode is 'development' when using watch mode, otherwise 'production'.
   @default [development]
  */
  modes?: Mode[];
  /**
    The target determines the type of transformation.
    @default 'web'
  */
  target?: Target;
  /**
    Sprkl configuration path.
    @default ${homedir()}/.sprkl/cli.json
  */
  config?: string;
  /**
    Enables running a command each time the server restarts, useful in 'development' mode.
    The main purpose is the use `sprkl apply` each restart so the code will be instrumented automatically.
  */
  exec?: {
    /**
      @default false
    */
    enabled?: boolean;
    /**
      Determines which mode to execute the given script.
      @default development
    */
    mode?: Mode;
    /**
      Execution script to run every time server is loaded.
      @default sprkl apply
   */
    script?: string;
    /**
      @default The current root directory
    */
    workingDirectory?: string;
  };
};

Other

For any other tooling or servers (like Remix), we provide Web server instrumentation, although this method is less preferred and is unstable.

This instrumentation tries to transform the javascript/ HTML files that are being served from that server. Since there are many implementations of frontend web servers, the code-level Sprkl instrumentation may not work, but OpenTelemetry instrumentation should work in any case.

Note that enabling the web server instrumentation with the webpack loader or rollup plugin can cause issues due to collision, so to be on the safe side prefer the Webpack loader or Rollup plugin.

Enable Sprkl web server instrumentation with the flag:

# Short form
sprkl --web-server=true -- <YOUR COMMAND>

# Long form
sprkl --opentelemetry.instrumentations.web-server.enabled=true -- <YOUR COMMAND>

# Disable with
sprkl --opentelemetry.instrumentations.web-server.enabled=false -- <YOUR COMMAND>

# Kubernetes
# To enable web server instrumentation in Kubernetes deploy the operator with the flag enabled.
sprkl --web-server=true k8s apply

Or add in the configuration file at ~/.sprkl/cli.json:

// filepath: ~/.sprkl/cli.json

{
  //...
  "opentelemetry": {
    "instrumentations": {
      "web-server": {
        "enabled": true
      },
    },
  },
  //...
}