Namespaces are a way to group error incidents, performance incidents and metrics from actions. AppSignal uses three namespaces by default:
web for web requestsfrontend for Front-end JavaScriptbackground 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.
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.
# 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
# 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
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
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
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
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
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.
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");
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.
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`)
appsignal.namespace attribute with a String value of the new namespace.
span.SetAttributes(attribute.String("appsignal.namespace", "admin"))
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");
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.
Further Reading
