AppSignal v1.1.1 Appsignal.Transaction

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.

Summary

Types

The transaction’s namespace

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

Types

namespace()
namespace :: :http_request | :background_job

The transaction’s namespace

t()
t :: %Appsignal.Transaction{id: term, resource: term}

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

Functions

complete()
complete :: :ok

Complete the current transaction. See complete/1.

complete(transaction)
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
finish()
finish :: :sample | :no_sample

Finish the current transaction. See finish/1.

finish(transaction)
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.

finish_event(name, title, body, body_format \\ 0)
finish_event(String.t, String.t, String.t, integer) :: Appsignal.Transaction.t

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

finish_event(transaction, name, title, body, body_format)
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.
generate_id()
generate_id :: String.t

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

lookup_or_create_transaction(origin \\ nil, namespace \\ :background_job)

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.

record_event(name, title, body, duration, body_format \\ 0)
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.

record_event(transaction, name, title, body, duration, body_format)
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(action)

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

set_action(transaction, action)

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")
set_error(name, message, backtrace)

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

set_error(transaction, name, message, backtrace)

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
set_meta_data(values)
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.

set_meta_data(key, value)

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

set_meta_data(transaction, key, value)

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")
set_queue_start(start \\ -1)
set_queue_start(integer) :: Appsignal.Transaction.t

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

set_queue_start(transaction, start)
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
set_sample_data(key, payload)
set_sample_data(String.t, any) :: Appsignal.Transaction.t

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

set_sample_data(transaction, key, payload)
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
start(transaction_id, namespace)

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. Must be one of :http_request, :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_event()
start_event :: Appsignal.Transaction.t

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

start_event(transaction)

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.

Macros

config()