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.

Configurations per Language

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.

ruby
# 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.

ruby
# 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. The second argument of Appsignal::Transaction.new accepts the namespace as a value (line 4).

ruby
# When creating a new transaction transaction = Appsignal::Transaction.create( SecureRandom.uuid, # Random transaction ID "admin", # Namespace Appsignal::Transaction::GenericRequest.new({}) # Default environment object )

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:

ruby
# 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.

Read More

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

elixir
# 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:

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

Read More

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.

javascript
import { setNamespace } from "@appsignal/nodejs"; setNamespace("custom-namespace");

Read more about how spans work in Node.js.

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.

python
from appsignal import set_namespace set_namespace("custom-namespace")

Read more about how spans work in Python.

Front-end JavaScript

In Front-end JavaScript applications AppSignal works with spans to track metadata such as a span's namespace. The namespace can only be set on the "root span", or the first span that is created without a parent. All children of this span will inherit the namespace of the parent span. When creating this root span, pass in the namespace option as a key with a String value that is the desired namespace name, as demonstrated in the below example:

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

Read more about how spans work in Front-End JavaScript.

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!

Further Reading