AppSignal v1.0.0 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

namespace()

The transaction’s namespace

t()

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

Functions

complete()

Complete the current transaction. See complete/1

complete(transaction)

Complete a transaction

finish()

Finish the current transaction. See finish/1

finish(transaction)

Finish a transaction

finish_event(name, title, body, body_format \\ 0)

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

finish_event(transaction, name, title, body, body_format)

Finish an event

generate_id()

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

record_event(name, title, body, duration, body_format \\ 0)

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

record_event(transaction, name, title, body, duration, body_format)

Record a finished event

set_action(action)

Set action of the current transaction. See set_action/1

set_action(transaction, action)

Set action of a transaction

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

set_meta_data(values)

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

set_queue_start(start \\ -1)

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

set_queue_start(transaction, start)

Set queue start time of a transaction

set_sample_data(key, payload)

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

set_sample_data(transaction, key, payload)

Set sample data for a transaction

start(transaction_id, namespace)

Start a transaction

start_event()

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

start_event(transaction)

Start an event

Macros

config()

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(String.t) :: Appsignal.Transaction.t

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

set_action(transaction, action)

set_action(Appsignal.Transaction.t | nil, String.t) :: Appsignal.Transaction.t

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_error(String.t, String.t, any) :: Appsignal.Transaction.t

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

set_error(transaction, name, message, backtrace)

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

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_meta_data(String.t, String.t) :: Appsignal.Transaction.t

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

set_meta_data(transaction, key, value)

set_meta_data(Appsignal.Transaction.t | nil, String.t, String.t) :: Appsignal.Transaction.t

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(String.t, namespace) :: 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. 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.