Groeperen met actienamen - AppSignal Documentation

Wanneer AppSignal gegevens van uw applicatie ontvangt, worden traces/transacties gegroepeerd op basis van de combinatie van hun namespace en actienaam. Standaard worden deze actienamen automatisch bepaald op basis van uw framework (bijv. Controller#action_name, BackgroundWorker#perform, enz.). Wanneer de automatisch bepaalde actienaam niet goed genoeg is, kunt u de actienaam aanpassen. Deze gids legt uit hoe u actienamen kunt aanpassen in verschillende taalintegraties.

Actienamen zijn niet bedoeld om uniek te zijn! Gebruik geen variabelen om de actienamen aan te passen, want hierdoor wordt per voorval een nieuw incident aangemaakt. Dit maakt het incidentoverzicht moeilijk bruikbaar en verhindert correcte groepering en trendanalyse.Gebruik altijd statische strings voor actienamen. Interpoleer nooit variabelen, gebruikersinvoer of dynamische gegevens in actienamen.

Waarom actienamen aanpassen?

Verbeterde duidelijkheid: Geef beschrijvender namen aan complexe operaties.
Aangepaste groepering: Bepaal hoe applicatiegegevens worden georganiseerd in AppSignal.

Wanneer automatische actienamen tekortschieten

Hier zijn enkele voorbeelden waarbij automatisch gegenereerde actienamen mogelijk niet goed genoeg zijn:

Catch-all routes: In applicaties die catch-all routes of dynamische routering gebruiken (zoals /api/:entity/:action), kan de standaard actienaam iets generieks zijn zoals ApiController#dispatch.
Multifunctionele taken: Background workers en scripts die verschillende soorten werk afhandelen op basis van parameters die allemaal onder dezelfde actienaam zouden worden gegroepeerd (bijv. GenericWorker#perform).
GraphQL resolvers: Deze kunnen allemaal onder één enkele actienaam worden gegroepeerd (bijv. POST /graphql), ondanks dat ze veel verschillende soorten operaties afhandelen.

Ruby

In Ruby-applicaties kunt u de Appsignal.set_action helper gebruiken om de actienaam aan te passen:

# In a Rails controller
class PaymentsController < ApplicationController
  def process_payment
    provider = params[:payment][:provider]

    # GOOD: Change the action name from "PaymentsController#process_payment"
    # to something more specific about the operation
    if provider == "creditcard"
      Appsignal.set_action("PaymentsController#process_payment (creditcard)")
    end

    # BAD: Don't use a dynamic value, it creates too many action names
    # Appsignal.set_action("PaymentsController#process_#{provider}")

    # Rest of your code
  end
end

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen met de Appsignal.set_action helper. Het is ook mogelijk om de actienaam te configureren bij het aanmaken van een transactie met behulp van de Appsignal.monitor helper. Deze accepteert de actienaam als keyword-argument.

# When creating a new transaction
Appsignal.monitor(action: "script/custom_script") do
  # Your code to instrument
end

Elixir

In Elixir-applicaties kunt u de Appsignal.Span.set_name/2 functie gebruiken om de actienaam aan te passen op de root span:

# In a Phoenix controller
defmodule MyAppWeb.PaymentController do
  use MyAppWeb, :controller

  def process(conn, params) do
    # GOOD: Set a custom static action name based on payment type
    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

    # BAD: Don't use a dynamic value, it creates too many action names
    # Appsignal.Span.set_name(
    #   Appsignal.Tracer.root_span(),
    #   "PaymentController#process_#{payment_type}"
    # )

    # Rest of your code

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

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen met de Appsignal.Span.set_name/2 functie.

Node.js

In Node.js-applicaties kunt u de setRootName helper uit het AppSignal-pakket gebruiken om actienamen aan te passen:

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

// In an Express.js route handler
app.post("/payments", (req, res) => {
  const paymentType = req.body.type || "unknown";

  // GOOD: Set a custom action name based on payment type
  if (paymentType === "creditcard") {
    setRootName("PaymentsController#process_payment (creditcard)");
  }

  // BAD: Don't use a dynamic value, it creates too many action names
  // setRootName(`PaymentsController#process_${paymentType}`);

  // Rest of your code

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

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen met de setRootName helper.

Python

In Python-applicaties kunt u de set_root_name helper uit het AppSignal-pakket gebruiken om actienamen aan te passen:

from appsignal import set_root_name

# In a Django view
def process_payment(request):
    payment_type = request.POST.get('type', 'unknown')

    # GOOD: Set a custom action name based on payment type
    if payment_type == "creditcard":
        set_root_name("PaymentsView#process_payment (creditcard)")

    # BAD: Don't use a dynamic value, it creates too many action names
    # set_root_name(f"PaymentsView#process_{payment_type}")

    # Rest of your code

    return HttpResponse("Payment processed")

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen met de set_root_name helper.

Front-end JavaScript

In front-end JavaScript-applicaties kunt u de setAction helper uit het AppSignal-pakket gebruiken om actienamen aan te passen:

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

  // GOOD: Set a custom action name based on form type
  if (formType === "checkout") {
    span.setAction("CheckoutPage#submit_form (checkout)");
  }

  // BAD: Don't use a dynamic value, it creates too many action names
  // span.setAction(`CheckoutPage#submit_${formType}_form`);

  // Rest of your code
});

U kunt ook de actienaam van een bestaande span bijwerken:

// Get the current active span
const span = appsignal.getActiveSpan();

function handlePaymentMethodSelection(method) {
  // GOOD: Set a custom action name based on payment method
  if (method === "creditcard") {
    span.setAction("PaymentForm#select_method (creditcard)");
  }

  // BAD: Don't do this - using a variable creates too many action names
  // span.setAction(`PaymentForm#select_${method}`);

  // Rest of your code
}

Go

In Go-applicaties werkt AppSignal met OpenTelemetry, dat spans gebruikt om metadata bij te houden, zoals de actienaam. Stel op een willekeurige span in de trace een appsignal.action_name attribuut in met een String-waarde om de actienaam aan te passen:

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

	// GOOD: Set a custom action name based on payment type
	if paymentType == "creditcard" {
		span.SetAttributes(attribute.String("appsignal.action_name", "PaymentHandler#process_payment (creditcard)"))
	}

	// BAD: Don't use a dynamic value, it creates too many action names
	// span.SetAttributes(attribute.String("appsignal.action_name", fmt.Sprintf("PaymentHandler#process_%s", paymentType)))

	// Rest of your code

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

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen door het appsignal.action_name attribuut op de actieve span in te stellen.

Java

In Java-applicaties werkt AppSignal met OpenTelemetry, dat spans gebruikt om metadata bij te houden, zoals de actienaam. Stel op een willekeurige span in de trace een appsignal.action_name attribuut in met een String-waarde om de actienaam aan te passen:

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

        // GOOD: Set a custom action name based on payment type
        if ("creditcard".equals(type)) {
            span.setAttribute("appsignal.action_name", "PaymentController#processPayment (creditcard)");
        }

        // BAD: Don't use a dynamic value, it creates too many action names
        // span.setAttribute("appsignal.action_name", "PaymentController#process_" + type);

        // Rest of your code

        return "Payment processed";
    }
}

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen door het appsignal.action_name attribuut op de actieve span in te stellen.

PHP

In PHP-applicaties kunt u de Appsignal::setAction() helper-methode uit het AppSignal-pakket gebruiken om actienamen aan te passen:

<?php

use Appsignal\Appsignal;

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

        // GOOD: Set a custom action name based on payment type
        if ($paymentType === 'creditcard') {
            Appsignal::setAction('PaymentController::processPayment (creditcard)');
        }

        // BAD: Don't use a dynamic value, it creates too many action names
        // Appsignal::setAction("PaymentController::process_{$paymentType}");

        // Rest of your code

        return 'Payment processed';
    }
}

Voor background jobs, taken en scripts kunt u de actienaam op dezelfde manier instellen door het appsignal.action_name attribuut op de actieve span in te stellen.

Best practices

Volg deze richtlijnen bij het aanpassen van actienamen:

Wees consistent: Gebruik een consistent naamgevingspatroon in uw hele applicatie.
Wees specifiek: Vermeld relevante informatie waarmee de operatie kan worden geïdentificeerd.
Vermijd hoge cardinaliteit: Neem geen unieke ID’s of waarden op die per uitvoering unieke actienamen zouden creëren.
Gebruik statische strings: Interpoleer nooit variabelen of dynamische gegevens in actienamen.
Volg de naamgeving van de codebase: Gebruik naamgevingspatronen zoals Controller#action die overeenkomen met de structuur van uw applicatie, zodat de locatie in de code kan worden gevonden.
Gebruik in plaats daarvan tags of metadata: Gebruik tags en metadata om variabele informatie zoals betalingsproviders of gebruikerstypen bij te houden, in plaats van deze in actienamen op te nemen.

Hoe verschillende operaties met dezelfde actienaam af te handelen

In plaats van dynamische actienamen aan te maken, gebruikt u een combinatie van:

Statische actienamen: Gebruik beschrijvende maar statische actienamen.
Tags: Voeg tags toe met de variabele informatie (bijv. provider: stripe, operation_type: refund).
Aangepaste attributen: Voeg aanvullende metadata toe aan de trace/transactie.

Voorbeeld:

# Instead of this:
# Appsignal.set_action("PaymentController#process_#{provider}")

# Do this:
Appsignal.set_action("PaymentController#process_payment")
Appsignal.add_tags(
  provider: provider,
  operation: operation
)

Met deze aanpak kunt u:

Gerelateerde operaties onder één enkele actienaam groeperen.
Filteren en zoeken op basis van tags.
Een overzichtelijk incidentoverzicht behouden.

Deploy

Nadat u aangepaste actienamen heeft geïmplementeerd, kunt u uw applicatie deployen. Nieuwe traces/transacties zullen uw aangepaste actienamen gebruiken in de AppSignal-dashboards.

Historische gegevens blijven de oorspronkelijke actienamen gebruiken. Alleen nieuw gerapporteerde acties zullen de aangepaste namen gebruiken die u heeft gedefinieerd.

Verschijnen uw aangepaste actienamen niet correct? Aarzel niet om contact op te nemen met ons supportteam voor hulp!

​Waarom actienamen aanpassen?

​Wanneer automatische actienamen tekortschieten

​Acties aanpassen per taal

​Ruby

​Elixir

​Node.js

​Python

​Front-end JavaScript

​Go

​Java

​PHP

​Best practices

​Hoe verschillende operaties met dezelfde actienaam af te handelen

​Deploy

​Verder lezen

Waarom actienamen aanpassen?

Wanneer automatische actienamen tekortschieten

Acties aanpassen per taal

Ruby

Elixir

Node.js

Python

Front-end JavaScript

Go

Java

PHP

Best practices

Hoe verschillende operaties met dezelfde actienaam af te handelen

Deploy

Verder lezen