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.

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.

Configurations per Language

• Ruby
• Elixir
• Node.js
• Python
• Front-end JavaScript
• Go

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

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

# 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

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

Read More

• Appsignal.Span.set_namespace Helper Method Documentation
• Elixir Namespace Decorator
• Elixir Namespace Instrumentation Helper

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");

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.

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:

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.

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.

PHP

In PHP 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 PHP 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 PHP.

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

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

Further Reading

• Filtering App Data
• Namespaces
• Ignoring Namespaces