Terminology
At AppSignal we use a lot of technical terms. Read on to learn more about the language of AppSignal. See the list of terminology on the right-hand side of this page.
Actions
Actions are the location in the code where an HTTP request, background job, cron job or task is started. For Ruby on Rails and Elixir's Phoenix apps, this is the controller and action combination, such as BlogPostsController#create or Api::UsersController#index. For background jobs, this will be the worker/job name, such as UserMailer#sign_up_mail.
Actions are used to group issues along with the namespace and error.
Agent
AppSignal uses an "agent" to communicate with the AppSignal servers and instrument the hosts an application is running on. The host data is used in our host metrics feature.
The agent is started by the language-specific library and runs as a separate UNIX process on the application's host. The language library and agent communicate with each other through a UNIX socket using an extension.
The transaction instrumentation data collected by the agent is sent to the AppSignal servers. The transaction data is processed and used to detect events worth alerting users about.
Read more about how the AppSignal agent operates and the life cycle of an AppSignal request.
Allocations
During an HTTP request or a background job, an application uses memory. Every data structure that's loaded and object that's instantiated takes up memory. When a request or job handles a lot of data a lot more memory may be used than is normal.
The AppSignal integration libraries keep track of allocations per transaction. The integration also keeps track of what part of the application allocates more memory objects than others, so it's possible to see if the application's ORM or template library is taking up more memory.
On AppSignal.com the number of allocations is displayed in an Integer for an action, event groups and specific events. This allocation number is the number of objects that have been created in memory during an action/group/event. The size of the created object is not tracked.
Anomaly detection
Anomaly detection is an AppSignal feature that allows users to detect abnormalities in their apps. An anomaly could be something like an increased error rate or a limited amount of free memory on the app's host.
Anomaly detection works with trigger threshold conditions that create Alerts when their threshold is reached. When an Alert is opened, AppSignal will send notifications to whichever notifiers have been selected for the specific trigger.
See our documentation about Anomaly detection for more information.
API
An API is an "Application Programming Interface". The term API is broad and is used in many ways. In the context of our documentation, we refer to the AppSignal HTTP REST API when using "API".
The AppSignal API is a HTTP REST API which can be used to retrieve data from the AppSignal servers and augment the existing data with more information such as Markers.
The API differs from the Push API in its purpose. While the Push API is used to send data to AppSignal by the agent, the HTTP REST API is primarily used to retrieve data from AppSignal. This allows users to use the available data in other tooling.
You can read more about our API in our API documentation.
API key
To connect with the AppSignal API it's necessary to be authenticated. Every user has their API key to authenticate with AppSignal.
Your API key can be found on your user profile.
This key is not to be confused with the Push API key which is used by applications with an AppSignal agent installed.
Applications
Applications (previously known as "sites", also referred to as "apps") are Ruby and Elixir applications monitored by AppSignal.
After installing the AppSignal library in an application AppSignal starts monitoring these applications. Once we receive data from an application, we register it using the application name and environment it's running in.
An application can have multiple environments as long as every environment uses the same name.
- "Demo application" - Development
- "Demo application" - Production
- "Demo application" - Staging
- "Demo application" - Test
Multiple applications can exist in one organization.
Read more about applications in our Applications documentation.
AppSignal vs Appsignal vs appsignal
Wait, they're three different casings of the AppSignal name?
Yes! Let's explain:
| Casing | Usage |
|---|---|
AppSignal | The brand name of the company, the application and almost everything else related to AppSignal. This is the version you should use when talking about AppSignal as a brand, product or service or stroopwaffle supplier. |
Appsignal | The library name of our AppSignal integrations (Ruby integration, Elixir integration, Node.js integration, Front-end integration etc.). Only used in the code context. |
appsignal | The AppSignal integration package names as published to package manager registries for the Ruby gem, Elixir package and packages prefix name, Node.js packages prefix and Front-end packages prefix, etc. |
Blog
We have a blog at blog.appsignal.com!
On our blog, we post all things relevant to AppSignal, such as new features, new major agent releases, Ruby Magic articles and other awesome stories from our internal process. Such as how to eat stroopwafels.
Changelog
We keep a full product changelog at appsignal.com/changelog.
All our new features, agent releases and other changes to the product can be found in this neatly organized list.
We also have a small indicator in our top navigation that notifies you if there's a new entry to the changelog.
Configuration
The configuration is part of the libraries running in applications. It tells the AppSignal libraries what to instrument in an application, which application it is and in which environment it's running.
The AppSignal libraries have multiple methods of configuration. The most common
method of configuration is the usage of an appsignal.yml configuration file.
The usage of environment variables is also recommended.
For the configuration of the Ruby agent, we recommend you read the configuration topic to get started.
CPU usage
During the operation of an application, the CPU usage can vary wildly. Some operations of an application can request more CPU time than others.
Other factors can also affect the CPU usage. If the monitored application is not the only process on the host machine other processes can also affect the CPU usage metric. For example, if a database running on the same machine has to perform a complicated query it will request more CPU time.
On AppSignal.com the CPU usage of an application is displayed in two ways. For an action where an error/performance issue occurred and for host metrics. This way it's possible to see if the performance of an action was directly affected by a busy CPU or if the entire host was affected for longer periods.
Learn more about what CPU metrics mean on our blog.
Cross-Site Request Forgery
Cross-Site Request Forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application where they are authenticated.
A victim may click on a link sent to them via email or web chat, allowing the attacker to steal and use the victim's credentials. The severity of the attack can vary depending on the application and authorization access of the victim's account. An attacker may be able to make state-altering actions to a user's account, such as changing their login credentials, and can compromise an entire application in severe cases, such as when a victim is an administrator.
Elixir Alchemy
Want to learn more about Elixir? In our email series Elixir Alchemy (1x p/mo) we dive deeper into Elixir and Erlang. You can sign up here: appsignal.com/elixir-alchemy.
Environments
Most applications can be run in different modes. During development of an application other rules apply and errors are not usually shown in the form of a "500 internal server error" page as they do in "production".
AppSignal also understands the concept of an environment allowing different settings be configured per environment. For every environment a separate application is created on AppSignal.com to be configured with its own set of alerting rules and third-party integrations.
Errors
Errors are problems that occur during the runtime of an application. This can be anything ranging from a catastrophic failure causing the application to crash or a simple typo causing an error page.
Once an error occurs in an application AppSignal sends an alert and records the details of the error for later viewing on AppSignal.com.
Read more about the errors feature on our tour page. To learn more about error handling in Ruby, read our Exception handling topic describing how to effectively track errors with AppSignal.
Errors are reported as issues. Learn more about what issues are.
Events
An event is something that happened. This is a very vague statement because the concept of an event is something very high-level. An error is an event, and so is an performance issue.
AppSignal monitors many events inside an application and on a server using host metrics. By collecting many different types of events and combining the data we hope to provide an as complete as possible picture to gain more insights into applications performance.
Also, see instrumentation events documentation.
Extension
The AppSignal libraries and agent are in constant communication with each other. The libraries send data to the agent over a UNIX socket. To do so the libraries use an extension for the programming language they're written in. This extension is written in C and Rust, and installed when the language-specific agent is installed.
Read more about the AppSignal extension operates and the life cycle of an AppSignal request.
Impact
The impact of an action on an application is based on its usage compared to other actions. When one controller action or job takes more time or is executed more often than others its impact grows.
For example:
- Action A is triggered 1000 times with an average duration of 0.5 seconds. The combined duration is 500 seconds.
- Action B is triggered 500 times with an average duration of 3 seconds. The combined duration is 1500 seconds.
The total combined duration of both actions is 2000 seconds.
- Action A has an impact of 25% (500 / 2000).
- Action B has an impact of 75% (1500 / 2000).
Instrumentation
Instrumentation is what powers AppSignal. Without it, we wouldn't know anything about what's going on inside Applications.
Instrumentation is hooks inside or around frameworks and libraries AppSignal uses to monitor application code. This instrumentation reports errors and slow code which is sent to AppSignal for analysis. Once a problem is detected an alert is sent.
Learn more about Ruby instrumentation.
Instrumentation events
Events are blocks of code that are executed. These can be methods, functions or smaller parts of either. Events can be nested to show hierarchy and the total duration of operations. These individual events make it possible to see which parts of the code are slower than others.
At the top issue pages, we also group the event durations by group name, following our event naming, to give insights into what part of the app takes the longest.
Some types of events that can be shown are database queries, JSON parsing, views rendering, HTTP requests, custom instrumentation, etc.
Each event is shown on performance issue detail pages in the "performance timeline". If we detect the same event is repeated more than once in succession, we will mark them as potential N+1 events, such as N+1 queries.
Also see instrumentation.
Issues
Whenever AppSignal detects a new error, an issue is created. Whenever AppSignal detects a new potential slow request, background job, etc. a new issue is created. This issue is grouped by action, namespace and error.
Error issues also support errors without action, as an error can occur outside of an action, such as in the app's framework before reaching the app's own code. Performance issues without an action are silently ignored.
The action, namespace and the error type are the way we group issues. If an error of a new type occurs on the same action in the same namespace as another error issue, a new issue will be created for that error. If another potential slow request is detected on another endpoint or background job, a new issue will be created for that endpoint/job.
Per issue, it's possible to configure notification settings, assignment, state (open/closed/work in progress), and severity.
Libraries
AppSignal uses language-specific libraries to monitor applications. Currently we have a Ruby gem and Elixir package. These libraries include hooks into frameworks and libraries to instrument code blocks such as database calls, file system calls and view rendering.
Every library is specialized in the instrumentation of its subject language. Most AppSignal libraries also includes an "agent" which the libraries use to communicate with the AppSignal servers.
Read more about how the AppSignal agent operates and the life cycle of an AppSignal request.
Library integrations
AppSignal libraries integrate with a variety of different libraries and frameworks specific to the programming language. The Ruby gem integrates with pure Ruby, Rails, Sinatra and other available frameworks. The Elixir package integrates with pure Elixir and Phoenix.
These automatic integrations make it easier to get more insight into applications without having to add AppSignal instrumentation manually.
Read more about what Ruby integrations we offer.
Markers
Markers are little icons used in graphs on AppSignal.com to indicate a change. This can be a code deploy using a "Deploy marker" or a special event with a "Custom marker". These custom markers can be anything from scaling operations, sudden spikes in traffic or when a database is experiencing issues.
Read more about markers.
Metadata
Metadata is data that gives information about other data.
Metadata is information about an error or performance issue that provides more context to the data collected. By sending extra metadata on a sample it's easier to track down what the circumstances were around the particular issue.
By default the metadata of a request includes the hostname on which the issue occurred, the SCM revision on which the application is running, and the request ID of the request the sample was derived from. It also includes data such as the request path and the request method for web requests.
Metrics
AppSignal provides two kinds of metrics.
Custom metrics allow the collection of data from just about anything. With a couple lines of code it's possible to track and graph data such as the number of registered users, visits to a page, database sizes, etc.
Host metrics are about data from the server an application is running on. Data such as CPU usage, load averages, memory usage, etc. give more insight into performance issues than just the code itself. Maybe the disk space is running out causing the application to run much slower.
Read more about metrics on our tour page.
Namespace
Namespaces are grouping mechanisms used by AppSignal to differentiate between different parts of the same application. By default, AppSignal splits an application up into two namespaces: "Web" and "Background".
HTTP requests that are being monitored by AppSignal will be added to the "Web" namespace and jobs performed by background job libraries are added to the "Background" namespace. It's also possible to configure your namespaces to differentiate between requests on an application and a private administration panel.
For more information about namespaces, please see our namespaces documentation.
Notifications
AppSignal sends notifications whenever a problem is detected with an application. These notifications can be email messages, Slack messages, a PagerDuty notification, and more depending on which third-party integrations are configured.
We send notifications about errors, slow requests and Anomaly detection alerts that occur in an application using an AppSignal library. Once a problematic event is detected a notification is sent out to alert users of a problem.
Organizations
Organizations are used to group applications and users for a business. A business can have many users and clients that can be notified] whenever there's a problem with their applications.
Billing for applications is done on organization level rather than per application.
Team management is made easy using organizations. Whole teams can invited to an organization so there's no need for sharing sign-in details.
Read more about organizations in our Organizations documentation.
Owners
Organizations have people that manage the organization. These owners decide who's a member of an organization, in which team they do or do not belong and decide how the billing is done.
Organization owners can manage everything about an organization and the applications that belong to it. If you do not have permission to view or change something, ask your organization's owner to change it for you or give you more permission.
Performance issues
Using performance monitoring it's possible to deep dive into individual requests and see what parts of an application are slow. Using this information it's possible to find and improve problem areas.
When AppSignal detects a slow web request or operation it will send notifications, because slow code can be as damaging as an error appearing.
Performance issues are grouped by action and namespace. On performance issue detail pages more information is available about each action. Not all issues are an "issue". It's up to you to determine if an HTTP request of 200ms is too slow.
Potential slow requests and background jobs are reported as performance issues. Learn more about what issues are.
Read more about the performance feature on our tour page.
Push API
The AppSignal "Push API" is the API endpoint used by the AppSignal agent to send the collected data. This is different from the normal AppSignal API which is primarily used to read data and add more context to the data that's sent to AppSignal.
This Push API is the API where application instrumentation is sent from applications using the Push API key.
Push API key
The "Push API key" is a write-only API key used by applications to authenticate themselves when sending data to the AppSignal servers. Apps report data to the Push API and authenticate using this key.
There are several kinds of Push API keys that apps can use for different use cases. All Push API keys can be found on the Push & deploy settings page.
- Organization-level Push API key: The recommended Push API key for back-end integrations, like Ruby, Elixir, Node.js, Python and Go. We recognize apps by a combination of the Push API key, app name and app environment, and create apps using this information if it does not yet exist.
- App-level Push API key: After creation, an app also gets assigned its app-level Push API key. This key can be used to send data to a specific app, even if the app is configured to use a different app name or app environment. This is used when moving apps between organizations without data loss, or when no app name or app environment can be set, like for the Vector integration.
- Front-end API key: This key is used by apps using our front-end integration to report data and can be found in the "Front-end error monitoring" section.
Note: These write-only keys are not to be confused with the user-specific API key which can be used to authenticate on the AppSignal API to retrieve data about your apps from our system.
Response time
The response time of an application's action is the time spent processing the action. The longer an action takes to perform the more it qualifies as a performance issue.
The duration of this action is displayed on AppSignal.com for performance issues and in graphs for controllers/jobs and on the host level.
Ruby Magic
Did you know we write articles about the magic that is Ruby? We do!
It's called Ruby Magic and you can sign up for it on appsignal.com/ruby-magic.
A list of all the Ruby Magic articles we've written so far can be found on our blog.
Samples
When a page request is slow a hundred times in a row, it's not as relevant to see all the slow requests, a smaller sample of these requests tells the same story.
Instead, the AppSignal agent only sends a small set of performance issues to the AppSignal servers. This saves data sent to the servers, the data processed on the application host and the AppSignal servers, while still telling the same story about the issues.
Stroopwafels
Also written as "stroopwaffles".
At AppSignal, we love stroopwafels. We've shipped over 25,000 of them to customers, friends and conferences. If you work at a tech company and have had a stroopwaffle at the office, chances it came from us.
We've written a whole article about what stroopwafels are and how you should eat them. Read on to become a stroopwafel expert.
Tags
Error and performance issue samples can be tagged. By tagging these samples it's easier to find and identify certain issues. By tagging it's possible to add more metadata to a sample that can be used in link templates to easily link to the relevant data in your application.
Read more about tagging requests.
Teams
To manage members of organizations, organization owners can utilize teams to give access to applications. Users that are part of a team can only access the applications the team they belong to have access to. If a user is part of more than one team this user can access all applications of all the teams they belong to.
Teams give permission management to owners of an organization to limit user access to applications without the need for multiple organizations.
Read more about organization team management.
Third-party integrations
AppSignal.com provides connections with other services such as Slack and PagerDuty to more effectively alert users about problems that are detected. These integrations can be managed through the UI on AppSignal.com on an application-by-application basis.
Read more about which third-party integrations we offer.
Transactions
Transactions are created by the AppSignal libraries for every monitored web request and background job. Within this transaction, the agents monitor for errors and slow code. A transaction is created at the start of a web request or when a background job is started. Once the request or job finishes or crashes, the transaction is closed and sent to the agent for processing.
Tags and metadata are added on transaction-level to more easily identify differences between transaction samples.
Throughput
The throughput of an application is the total number of requests sent through an action/job in a certain time frame. The throughput can differ per action and host.
On AppSignal.com the throughput is displayed per action and displayed in graphs for every host.
TLS
TLS stands for Transport Layer Security. TLS is a cryptographic protocol that provides secure connections for computer networks, for example, between a server and a web browser.
Queue time
When a server or application is busy processing a lot of requests certain requests may be queued before they are processed. The time waiting to be processed is referred to as "queue time".
Since queue time can negatively affect users' experience using an application this metric is tracked by AppSignal for HTTP requests and background jobs.
For the background jobs, this represents the time between the request being queued (by a web request) and it being picked up by the background worker (sidekiq).
User account
Every user using AppSignal has a user account. With this user account you can configure notification preferences.
Many users can belong to one or more organizations. No need for separate user accounts for every organization.
Organizations manage which users can access which applications and who can manage the billing as an owner.