AppSignal v1.4.10 Appsignal.Transaction View Source

Functions related to AppSignal transactions

This module contains functions for starting and stopping an AppSignal transaction, recording events and collecting metrics within a transaction, et cetera.

All functions take a Transaction as their first parameter. It is possible to omit this parameter, in which case it is assumed that the calling process has already an associated Transaction (the “current” transaction). This is the case after Transaction.start/2 has been called from within the same process.

Link to this section Summary

Types

t()

Datatype which is used as a handle to the current AppSignal transaction

Functions

Complete the current transaction. See complete/1

Complete a transaction

Finish the current transaction. See finish/1

Finish a transaction

Finish an event for the current transaction. See finish_event/5

Generate a random id as a string to use as transaction identifier

Record a finished event for the current transaction. See record_event/6

Set action of the current transaction. See set_action/1

Set action of a transaction

Set an error for a the current transaction. See set_error/4

Set an error for a transaction

Set metadata for the current transaction from an enumerable. The enumerable needs to be a keyword list or a map

Set metadata for the current transaction. See set_meta_data/3

Set metadata for a transaction

Set queue start time of the current transaction. See set_queue_start/2

Set queue start time of a transaction

Set the request metadata, given a Plug.Conn.t

Set sample data for the current transaction. See set_sample_data/3

Set sample data for a transaction

Start a transaction

Start an event for the current transaction. See start_event/1

Start an event

Given the transaction and a %Plug.Conn{}, try to set the Phoenix controller module / action in the transaction

Link to this section Types

Link to this type t() View Source
t() :: %Appsignal.Transaction{id: term(), resource: term()}

Datatype which is used as a handle to the current AppSignal transaction.

Link to this section Functions

Link to this function complete() View Source
complete() :: :ok

Complete the current transaction. See complete/1.

Link to this function complete(transaction) View Source
complete(Appsignal.Transaction.t() | nil) :: :ok

Complete a transaction

Call this after finishing a transaction (and adding sample data if necessary).

  • transaction: The pointer to the transaction this event occurred in
Link to this function finish() View Source
finish() :: :sample | :no_sample

Finish the current transaction. See finish/1.

Link to this function finish(transaction) View Source
finish(Appsignal.Transaction.t() | nil) :: :sample | :no_sample

Finish a transaction

Call this when a transaction such as a http request or background job ends.

  • transaction: The pointer to the transaction this event occurred in

Returns :sample whether sample data for this transaction should be collected.

Link to this function finish_event(name, title, body, body_format \\ 0) View Source
finish_event(String.t(), String.t(), String.t(), integer()) :: Appsignal.Transaction.t()

Finish an event for the current transaction. See finish_event/5.

Link to this function finish_event(transaction, name, title, body, body_format) View Source
finish_event(Appsignal.Transaction.t() | nil, String.t(), String.t(), any(), integer()) :: Appsignal.Transaction.t()

Finish an event

Call this when an event ends.

  • transaction: The pointer to the transaction this event occurred in
  • name: Name of the category of the event (sql.query, net.http)
  • title: Title of the event (‘User load’, ‘Http request to google.com’)
  • body: Body of the event, should not contain unique information per specific event (select * from users where id=?)
  • body_format Format of the event’s body which can be used for sanitization, 0 for general and 1 for sql currently.
Link to this function generate_id() View Source
generate_id() :: String.t()

Generate a random id as a string to use as transaction identifier.

Link to this function lookup_or_create_transaction(origin \\ nil, namespace \\ :background_job) View Source

Return the transaction for the given process

Creates a new one when not found. Can also return nil; in that case, we should not continue submitting the transaction.

Link to this function record_event(name, title, body, duration, body_format \\ 0) View Source
record_event(String.t(), String.t(), String.t(), integer(), integer()) :: Appsignal.Transaction.t()

Record a finished event for the current transaction. See record_event/6.

Link to this function record_event(transaction, name, title, body, duration, body_format) View Source
record_event(Appsignal.Transaction.t() | nil, String.t(), String.t(), String.t(), integer(), integer()) :: Appsignal.Transaction.t()

Record a finished event

Call this when an event which you cannot track the start for ends. This function can only be used for events that do not have children such as database queries. GC metrics and allocation counts will be tracked in the parent of this event.

  • transaction: The pointer to the transaction this event occurred in
  • name: Name of the category of the event (sql.query, net.http)
  • title: Title of the event (‘User load’, ‘Http request to google.com’)
  • body: Body of the event, should not contain unique information per specific event (select * from users where id=?)
  • duration: Duration of this event in nanoseconds
  • body_format Format of the event’s body which can be used for sanitization, 0 for general and 1 for sql currently.

Set action of the current transaction. See set_action/1.

Link to this function set_action(transaction, action) View Source

Set action of a transaction

Call this when the identifying action of a transaction is known.

  • transaction: The pointer to the transaction this event occurred in
  • action: This transactions action ("HomepageController.show")
Link to this function set_error(name, message, backtrace) View Source
set_error(String.t(), String.t(), any()) :: Appsignal.Transaction.t()

Set an error for a the current transaction. See set_error/4.

Link to this function set_error(transaction, name, message, backtrace) View Source
set_error(Appsignal.Transaction.t() | nil, String.t(), String.t(), any()) :: Appsignal.Transaction.t()

Set an error for a transaction

Call this when an error occurs within a transaction.

  • transaction: The pointer to the transaction this event occurred in
  • name: Name of the error (RuntimeError)
  • message: Message of the error (‘undefined method call for something’)
  • backtrace: Backtrace of the error; will be JSON encoded
Link to this function set_meta_data(values) View Source
set_meta_data(Enum.t()) :: Appsignal.Transaction.t()

Set metadata for the current transaction from an enumerable. The enumerable needs to be a keyword list or a map.

Link to this function set_meta_data(transaction, values) View Source

Set metadata for the current transaction. See set_meta_data/3.

Link to this function set_meta_data(transaction, key, value) View Source

Set metadata for a transaction

Call this when an error occurs within a transaction to set more detailed data about the error

  • transaction: The pointer to the transaction this event occurred in
  • key: Key of this piece of metadata ("email")
  • value: Value of this piece of metadata ("thijs@appsignal.com")
Link to this function set_queue_start(start \\ -1) View Source
set_queue_start(integer()) :: Appsignal.Transaction.t()

Set queue start time of the current transaction. See set_queue_start/2.

Link to this function set_queue_start(transaction, start) View Source
set_queue_start(Appsignal.Transaction.t() | nil, integer()) :: Appsignal.Transaction.t()

Set queue start time of a transaction

Call this when the queue start time in miliseconds is known.

  • transaction: The pointer to the transaction this event occurred in
  • queue_start: Transaction queue start time in ms if known
Link to this function set_request_metadata(transaction, conn) View Source
set_request_metadata(Appsignal.Transaction.t() | nil, Plug.Conn.t()) :: Appsignal.Transaction.t()

Set the request metadata, given a Plug.Conn.t.

Link to this function set_sample_data(transaction, values) View Source
set_sample_data(Appsignal.Transaction.t(), Enum.t()) :: Appsignal.Transaction.t()
set_sample_data(String.t(), any()) :: Appsignal.Transaction.t()

Set sample data for the current transaction. See set_sample_data/3.

Link to this function set_sample_data(transaction, key, payload) View Source
set_sample_data(Appsignal.Transaction.t() | nil, String.t(), any()) :: Appsignal.Transaction.t()

Set sample data for a transaction

Use this to add sample data if finish_transaction returns true.

  • transaction: The pointer to the transaction this event occurred in
  • key: Key of this piece of metadata (params, session_data)
  • payload: Metadata (e.g. %{user_id: 1}); will be JSON encoded
Link to this function start(transaction_id, namespace) View Source
start(String.t(), atom()) :: Appsignal.Transaction.t()

Start a transaction

Call this when a transaction such as a http request or background job starts.

Parameters:

  • transaction_id The unique identifier of this transaction.
  • namespace The namespace of this transaction. Defaults to :background_job.

The function returns a %Transaction{} struct for use with the other transaction functions in this module.

The returned transaction is also associated with the calling process, so that processes / callbacks which don’t get the transaction passed in can still look it up through the Appsignal.TransactionRegistry.

Start an event for the current transaction. See start_event/1

Start an event

Call this when an event within a transaction you want to measure starts, such as an SQL query or http request.

  • transaction: The pointer to the transaction this event occurred in.

Given the transaction and a %Plug.Conn{}, try to set the Phoenix controller module / action in the transaction.

Link to this function try_set_action(transaction, conn) View Source