Gruppieren mit Aktionsnamen - AppSignal Documentation

Wenn AppSignal Daten von Ihrer Anwendung empfängt, werden Traces/Transaktionen nach der Kombination aus Namespace und Aktionsname gruppiert. Standardmäßig werden diese Aktionsnamen automatisch anhand Ihres Frameworks ermittelt (z. B. Controller#action_name, BackgroundWorker#perform usw.). Wenn der automatisch ermittelte Aktionsname nicht ausreicht, können Sie den Aktionsnamen anpassen. Dieser Leitfaden erklärt, wie Sie Aktionsnamen in verschiedenen Sprachintegrationen anpassen.

Aktionsnamen sind nicht dafür gedacht, eindeutig zu sein! Verwenden Sie keine Variablen, um Aktionsnamen anzupassen, da dies einen neuen Vorfall pro Auftreten erzeugt. Dadurch wird die Vorfallsübersicht schwer nutzbar und eine ordentliche Gruppierung und Trendanalyse verhindert.Verwenden Sie immer statische Zeichenketten für Aktionsnamen. Interpolieren Sie niemals Variablen, Benutzereingaben oder dynamische Daten in Aktionsnamen.

Warum Aktionsnamen anpassen?

Bessere Übersichtlichkeit: Stellen Sie aussagekräftigere Namen für komplexe Vorgänge bereit.
Angepasste Gruppierung: Steuern Sie, wie Anwendungsdaten in AppSignal organisiert werden.

Wenn automatische Aktionsnamen nicht ausreichen

Hier einige Beispiele, in denen automatisch generierte Aktionsnamen möglicherweise nicht ausreichen:

Catch-all-Routen: In Anwendungen, die Catch-all-Routen oder dynamisches Routing verwenden (wie /api/:entity/:action), könnte der Standard-Aktionsname etwas Generisches wie ApiController#dispatch sein.
Mehrzweck-Aufgaben: Background-Worker und Skripte, die je nach Parametern verschiedene Arten von Arbeit verarbeiten und alle unter demselben Aktionsnamen gruppiert würden (z. B. GenericWorker#perform).
GraphQL-Resolver: Diese könnten alle unter einem einzigen Aktionsnamen (z. B. POST /graphql) gruppiert werden, obwohl sie viele verschiedene Arten von Vorgängen verarbeiten.

Ruby

In Ruby-Anwendungen können Sie den Helfer Appsignal.set_action verwenden, um den Aktionsnamen anzupassen:

# In einem Rails-Controller
class PaymentsController < ApplicationController
  def process_payment
    provider = params[:payment][:provider]

    # GUT: Ändern Sie den Aktionsnamen von "PaymentsController#process_payment"
    # in etwas Spezifischeres zum Vorgang
    if provider == "creditcard"
      Appsignal.set_action("PaymentsController#process_payment (creditcard)")
    end

    # SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
    # Appsignal.set_action("PaymentsController#process_#{provider}")

    # Restlicher Code
  end
end

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise mit dem Helfer Appsignal.set_action setzen. Es ist auch möglich, den Aktionsnamen beim Erstellen einer Transaktion mit dem Helfer Appsignal.monitor zu konfigurieren. Er akzeptiert den Aktionsnamen als Schlüsselwortargument.

# Beim Erstellen einer neuen Transaktion
Appsignal.monitor(action: "script/custom_script") do
  # Ihr zu instrumentierender Code
end

Elixir

In Elixir-Anwendungen können Sie die Funktion Appsignal.Span.set_name/2 verwenden, um den Aktionsnamen am Root-Span anzupassen:

# In einem Phoenix-Controller
defmodule MyAppWeb.PaymentController do
  use MyAppWeb, :controller

  def process(conn, params) do
    # GUT: Setzen Sie einen benutzerdefinierten statischen Aktionsnamen basierend auf dem Zahlungstyp
    payment_type = Map.get(params, "type", "unknown")

    if payment_type == "creditcard" do
      Appsignal.Span.set_name(
        Appsignal.Tracer.root_span(),
        "PaymentController#process_payment (creditcard)"
      )
    end

    # SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
    # Appsignal.Span.set_name(
    #   Appsignal.Tracer.root_span(),
    #   "PaymentController#process_#{payment_type}"
    # )

    # Restlicher Code

    render(conn, "success.html")
  end
end

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise mit der Funktion Appsignal.Span.set_name/2 setzen.

Node.js

In Node.js-Anwendungen können Sie den Helfer setRootName aus dem AppSignal-Paket verwenden, um Aktionsnamen anzupassen:

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

// In einem Express.js-Route-Handler
app.post("/payments", (req, res) => {
  const paymentType = req.body.type || "unknown";

  // GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf dem Zahlungstyp
  if (paymentType === "creditcard") {
    setRootName("PaymentsController#process_payment (creditcard)");
  }

  // SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
  // setRootName(`PaymentsController#process_${paymentType}`);

  // Restlicher Code

  res.send("Payment processed");
});

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise mit dem Helfer setRootName setzen.

Python

In Python-Anwendungen können Sie den Helfer set_root_name aus dem AppSignal-Paket verwenden, um Aktionsnamen anzupassen:

from appsignal import set_root_name

# In einer Django-View
def process_payment(request):
    payment_type = request.POST.get('type', 'unknown')

    # GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf dem Zahlungstyp
    if payment_type == "creditcard":
        set_root_name("PaymentsView#process_payment (creditcard)")

    # SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
    # set_root_name(f"PaymentsView#process_{payment_type}")

    # Restlicher Code

    return HttpResponse("Payment processed")

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise mit dem Helfer set_root_name setzen.

Front-end JavaScript

In Front-end-JavaScript-Anwendungen können Sie den Helfer setAction aus dem AppSignal-Paket verwenden, um Aktionsnamen anzupassen:

const span = appsignal.createSpan((span) => {
  const formType = getFormType();

  // GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf dem Formulartyp
  if (formType === "checkout") {
    span.setAction("CheckoutPage#submit_form (checkout)");
  }

  // SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
  // span.setAction(`CheckoutPage#submit_${formType}_form`);

  // Restlicher Code
});

Alternativ können Sie den Aktionsnamen eines bestehenden Spans aktualisieren:

// Den aktuellen aktiven Span abrufen
const span = appsignal.getActiveSpan();

function handlePaymentMethodSelection(method) {
  // GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf der Zahlungsmethode
  if (method === "creditcard") {
    span.setAction("PaymentForm#select_method (creditcard)");
  }

  // SCHLECHT: Tun Sie das nicht – die Verwendung einer Variable erzeugt zu viele Aktionsnamen
  // span.setAction(`PaymentForm#select_${method}`);

  // Restlicher Code
}

Go

In Go-Anwendungen arbeitet AppSignal mit OpenTelemetry, das Spans zur Nachverfolgung von Metadaten wie dem Aktionsnamen verwendet. Setzen Sie an einem beliebigen Span im Trace ein Attribut appsignal.action_name mit einem String-Wert, um den Aktionsnamen anzupassen:

package main

import (
	"context"
	"net/http"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
)

func processPaymentHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
	span := trace.SpanFromContext(ctx)

	paymentType := r.FormValue("type")

	// GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf dem Zahlungstyp
	if paymentType == "creditcard" {
		span.SetAttributes(attribute.String("appsignal.action_name", "PaymentHandler#process_payment (creditcard)"))
	}

	// SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
	// span.SetAttributes(attribute.String("appsignal.action_name", fmt.Sprintf("PaymentHandler#process_%s", paymentType)))

	// Restlicher Code

	w.WriteHeader(http.StatusOK)
	w.Write([]byte("Payment processed"))
}

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise setzen, indem Sie das Attribut appsignal.action_name am aktiven Span setzen.

Java

In Java-Anwendungen arbeitet AppSignal mit OpenTelemetry, das Spans zur Nachverfolgung von Metadaten wie dem Aktionsnamen verwendet. Setzen Sie an einem beliebigen Span im Trace ein Attribut appsignal.action_name mit einem String-Wert, um den Aktionsnamen anzupassen:

import io.opentelemetry.api.trace.Span;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PaymentController {

    @PostMapping("/payments")
    public String processPayment(@RequestParam String type) {
        Span span = Span.current();

        // GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf dem Zahlungstyp
        if ("creditcard".equals(type)) {
            span.setAttribute("appsignal.action_name", "PaymentController#processPayment (creditcard)");
        }

        // SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
        // span.setAttribute("appsignal.action_name", "PaymentController#process_" + type);

        // Restlicher Code

        return "Payment processed";
    }
}

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise setzen, indem Sie das Attribut appsignal.action_name am aktiven Span setzen.

PHP

In PHP-Anwendungen können Sie die Hilfsmethode Appsignal::setAction() aus dem AppSignal-Paket verwenden, um Aktionsnamen anzupassen:

<?php

use Appsignal\Appsignal;

class PaymentController
{
    public function processPayment()
    {
        $paymentType = $_POST['type'] ?? 'unknown';

        // GUT: Setzen Sie einen benutzerdefinierten Aktionsnamen basierend auf dem Zahlungstyp
        if ($paymentType === 'creditcard') {
            Appsignal::setAction('PaymentController::processPayment (creditcard)');
        }

        // SCHLECHT: Verwenden Sie keinen dynamischen Wert, das erzeugt zu viele Aktionsnamen
        // Appsignal::setAction("PaymentController::process_{$paymentType}");

        // Restlicher Code

        return 'Payment processed';
    }
}

Für Background-Jobs, Aufgaben und Skripte können Sie den Aktionsnamen auf die gleiche Weise setzen, indem Sie das Attribut appsignal.action_name am aktiven Span setzen.

Best Practices

Befolgen Sie beim Anpassen von Aktionsnamen diese Richtlinien:

Seien Sie konsistent: Verwenden Sie ein einheitliches Benennungsschema in Ihrer gesamten Anwendung.
Seien Sie spezifisch: Fügen Sie relevante Informationen hinzu, die helfen, den Vorgang zu identifizieren.
Vermeiden Sie hohe Kardinalität: Fügen Sie keine eindeutigen IDs oder Werte ein, die pro Ausführung eindeutige Aktionsnamen erzeugen würden.
Verwenden Sie statische Zeichenketten: Interpolieren Sie niemals Variablen oder dynamische Daten in Aktionsnamen.
Folgen Sie der Benennung des Codebase: Verwenden Sie Benennungsschemata wie Controller#action, die zu Ihrer Anwendungsstruktur passen, damit die Stelle im Code gefunden werden kann.
Verwenden Sie stattdessen Tags oder Metadaten: Verwenden Sie für die Nachverfolgung variabler Informationen wie Zahlungsanbieter oder Benutzertypen Tags und Metadaten, anstatt diese in Aktionsnamen einzubinden.

Wie Sie verschiedene Vorgänge mit demselben Aktionsnamen behandeln

Anstatt dynamische Aktionsnamen zu erstellen, verwenden Sie eine Kombination aus:

Statische Aktionsnamen: Verwenden Sie aussagekräftige, aber statische Aktionsnamen.
Tags: Fügen Sie Tags hinzu mit den variablen Informationen (z. B. provider: stripe, operation_type: refund).
Benutzerdefinierte Attribute: Fügen Sie zusätzliche Metadaten hinzu zur Trace/Transaktion.

Beispiel:

# Statt dessen:
# Appsignal.set_action("PaymentController#process_#{provider}")

# Tun Sie das:
Appsignal.set_action("PaymentController#process_payment")
Appsignal.add_tags(
  provider: provider,
  operation: operation
)

Dieser Ansatz ermöglicht Ihnen:

Verwandte Vorgänge unter einem einzigen Aktionsnamen zu gruppieren.
Nach Tags zu filtern und zu suchen.
Eine übersichtliche Vorfallsübersicht zu pflegen.

Deployment

Nachdem Sie benutzerdefinierte Aktionsnamen implementiert haben, deployen Sie Ihre Anwendung. Neue Traces/Transaktionen verwenden Ihre benutzerdefinierten Aktionsnamen in den AppSignal-Dashboards.

Historische Daten verwenden weiterhin die ursprünglichen Aktionsnamen. Nur neu gemeldete Aktionen verwenden die von Ihnen definierten benutzerdefinierten Namen.

Erscheinen Ihre benutzerdefinierten Aktionsnamen nicht korrekt? Zögern Sie nicht, unser Support-Team zu kontaktieren für Hilfe!

​Warum Aktionsnamen anpassen?

​Wenn automatische Aktionsnamen nicht ausreichen

​Aktionen pro Sprache anpassen

​Ruby

​Elixir

​Node.js

​Python

​Front-end JavaScript

​Go

​Java

​PHP

​Best Practices

​Wie Sie verschiedene Vorgänge mit demselben Aktionsnamen behandeln

​Deployment

​Weiterführende Literatur

Warum Aktionsnamen anpassen?

Wenn automatische Aktionsnamen nicht ausreichen

Aktionen pro Sprache anpassen

Ruby

Elixir

Node.js

Python

Front-end JavaScript

Go

Java

PHP

Best Practices

Wie Sie verschiedene Vorgänge mit demselben Aktionsnamen behandeln

Deployment

Weiterführende Literatur