Grouping with Namespaces

Namespaces are a way to group error incidents, performance incidents and metrics from actions. AppSignal uses three namespaces by default:

web for web requests
frontend for Front-end JavaScript
background for background jobs

Applications can have any number of namespaces, for example, you could have a separate namespace for your application’s administration panel, API or scheduled tasks. This guide will go through the steps needed to report actions in custom namespaces.

Want to know more about what namespaces can be used for? Check out this list: What Can You Do With Namespaces?

App Graphs Namespaces — The above image shows example graphs with multiple namespaces, splitting out a GraphQL API and the Web namespace.

Configuring Namespaces

Namespaces are defined by your application’s code. With small helpers, you can customize the namespace of an action. This guide will teach you how to split requests up into different namespaces. For this guide, we’ll create an “admin” and a “critical” namespace for background jobs.

Namespace names may only contain letters (a-z) and underscores
We do not recommend having more than 15 namespaces per application.

Ruby

In Rails we can use the before_action callback to call a method before a request is handled. In the code example below, we’ve created a before_action that calls the set_appsignal_namespace method. In this method we call the Appsignal.set_namespace helper method to configure “admin” as the namespace for this request. This also works if other controllers are subclasses of the AdminController.

# In a Rails controller
# app/controllers/admin_controller.rb
class AdminController < ApplicationController
  before_action :set_appsignal_namespace

  def set_appsignal_namespace
    # Configures all actions in this controller to report
    # in the "admin" namespace
    Appsignal.set_namespace("admin")
  end

  # Any other controller actions
end

Next we’ll define the namespace of code executed by our application’s Sidekiq background workers. To correctly namespace errors triggered in our background worker, we must define the namespace before any other code runs. In the example Sidekiq worker code below, we do this immediately in the perform method on line 7.

# In a Sidekiq worker
# app/workers/critical_worker.rb
class CriticalWorker
  include Sidekiq::Worker

  def perform
    # Configures this worker's jobs to report in the "critical" namespace
    Appsignal.set_namespace("critical")

    # The actual worker code
  end
end

It’s also possible to configure the namespace when creating a transaction using the Appsignal.monitor helper. It accepts the namespace as a keyword argument.

# When creating a new transaction
Appsignal.monitor(namespace: "admin") do
  # Your code to instrument
end

For transactions that have already been created, you can use the set_namespace method to configure the transaction’s namespace, like in the example below:

# When changing the namespace later on for a transaction
transaction.set_namespace("slow_admin")

A note on helper location

The set_namespace helpers used in this guide can be called in any action that is part of an AppSignal sample. We recommend calling this as early in the request or background job as possible, so the transaction is configured with the given namespace before any error occurs. Otherwise, if an error occurs, or anything else that stops the process, the transaction is sent to AppSignal before the set_namespace helper is called, and the sample is reported under the default namespace instead.

Appsignal.set_namespace helper method documentation

Elixir

In Phoenix controllers we use a plug to call a function before the request is handled by Phoenix. In the code example below we use plug to call the set_appsignal_namespace function (line 5). In this function we call the Appsignal.Span.set_namespace helper to configure the namespace for this request (line 10).

# In a Phoenix controller
defmodule AppsignalPhoenixExampleWeb.AdminController do
  use AppsignalPhoenixExampleWeb, :controller

  plug :set_appsignal_namespace

  defp set_appsignal_namespace(conn, _params) do
    # Configures all actions in this controller to report
    # in the "admin" namespace
    Appsignal.Span.set_namespace(Appsignal.Tracer.root_span(), "admin")
    conn
  end

  # ...
end

Next we’ll configure the namespace for a background job. To catch any errors from within the job within the desired namespace, Appsignal.Span.set_namespace must be called at the beginning of the function before any other code, like on line 4 of the below code example:

defmodule MyApp.CriticalJob do
  def run do
    # Configures this worker's jobs to report in the "critical" namespace
    Appsignal.Span.set_namespace(Appsignal.Tracer.root_span(), "critical")

    # The actual worker code
  end
end

It’s also possible to configure the namespace when creating a transaction. Please see the documentation for decorators or instrumentation helpers for more information on how to configure namespaces.

A note on helper location

The set_namespace helpers used in this guide can be called in any action that starts an AppSignal transaction. We recommend calling this as early in the request or background job as possible, so the transaction is configured with the given namespace before any error occurs. Otherwise, if an error occurs—or anything else that stops the process—the transaction is sent to AppSignal before the set_namespace code is called and it is reported under the default namespace instead.

Node.js

In Node.js applications, AppSignal works with OpenTelemetry, which uses spans to track metadata, such as which namespace a span belongs to. Use the setNamespace helper function as sampled below to set the namespace for the active span’s trace.

import { setNamespace } from "@appsignal/nodejs";

setNamespace("custom-namespace");

PHP

In PHP applications, AppSignal works with OpenTelemetry, which uses spans to track metadata, such as which namespace a span belongs to. Use the Appsignal::setNamespace helper method to set the namespace for the active span’s trace.

Appsignal::setNamespace("admin");

If you call this helper multiple times within a single trace, AppSignal uses the call whose span has the newest timestamp. Read more about how custom instrumentation works in PHP.

Python

In Python applications, AppSignal works with OpenTelemetry, which uses spans to track metadata, such as which namespace a span belongs to. Use the set_namespace helper function as sampled below to set the namespace for the active span’s trace.

from appsignal import set_namespace

set_namespace("custom-namespace")

Front-end JavaScript

In Front-end JavaScript applications AppSignal works with spans to track metadata such as a span’s namespace.

Unlike Ruby, Node.js, PHP, and Python, the Front-end JavaScript API does not have a global setNamespace / set_namespace helper. Instead, like Elixir, Go, and Java, you set the namespace directly on a span.

When creating this span, call setNamespace with a String value of the desired namespace name, as demonstrated in the below example:

const span = appsignal.createSpan();
span.setNamespace("admin"); // a custom namespace for this span (defaults to `frontend`)

Go

In Go applications, AppSignal works with OpenTelemetry, which uses spans to track metadata, such as which namespace a span belongs to. On any span in the trace, set a appsignal.namespace attribute with a String value of the new namespace.

span.SetAttributes(attribute.String("appsignal.namespace", "admin"))

Please see the Go custom instrumentation docs on how to fetch a span or create a new one. If multiple attributes with the appsignal.namespace attribute are found, the span with the newest timestamp is leading. Read more about how custom instrumentation works in Go.

Java

In Java applications, AppSignal works with OpenTelemetry, which uses spans to track metadata, such as which namespace a span belongs to. On any span in the trace, set a appsignal.namespace attribute with a String value of the new namespace.

span.setAttribute("appsignal.namespace", "admin");

Please see the Java custom instrumentation docs on how to fetch a span or create a new one. If multiple attributes with the appsignal.namespace attribute are found, the span with the newest timestamp is leading. Read more about how custom instrumentation works in Java.

Deploy

When your application is configured with its new namespace helpers, commit your changes and deploy the app. When the app starts/restarts, AppSignal will report actions under their new namespace 🥳!

Data from old deploys will remain grouped by their original namespace. Only newly reported actions will be grouped by their new namespaces.

Are namespaces not being reported correctly? Don’t panic, give us a shout and we will help you out!

Getting started

Guides

Configuring Namespaces

Configurations per Language

Ruby

A note on helper location

Read More

Elixir

A note on helper location

Read More

Node.js

PHP

Python

Front-end JavaScript

Go

Java

Deploy

Further Reading

​Configuring Namespaces

​Configurations per Language

​Ruby

A note on helper location

​Read More

​Elixir

​A note on helper location

​Read More

​Node.js

​PHP

​Python

​Front-end JavaScript

​Go

​Java

​Deploy

​Further Reading

Configuring Namespaces

Configurations per Language

Ruby

Read More

Elixir

A note on helper location

Read More

Node.js

PHP

Python

Front-end JavaScript

Go

Java

Deploy

Further Reading