Developer's Guide - Packaging and Sending Data
In This Topic
Once the Loupe Agent has captured data about your application, you need to be able to get that data moved to where you are so it can be analyzed and aggregated with other data. To make this easy, the Agent includes data packaging and sending tools:
- Server Integration: The Agent can automatically send sessions in the background to a Loupe Server via web protocols. Highly compatible with firewalls and no user involvement required.
- Packager: This is a class that performs all on-demand data packaging and movement. You can call this directly to perform packaging without the agent providing any user interface. This is safe from any application (Windows Service, ASP.NET, Console, or WinForms).
- Packager Dialog: This is a WinForms dialog that provides its own wizard user interface to package and send data. It can be invoked programmatically, from the Live Viewer, and via hot key (Ctrl-Alt-F4 by default) from within the application. For an overview of what the wizard looks like, see Developer's Guide - Packager Utility.
- Gibraltar.Package: This is a stand-alone executable that invokes the PackagerDialog. It requires no code changes on your part and is designed for situations where you want to provide a user interface but aren't in a WinForms application, such as a Windows Service or ASP.NET application.
Packager Wizard in Action
|
What Does the Packager Do?
The packager selects session files from the local repository on the computer where it's run, stores them into a Package Repository, and then stores the package repository to a location of your choosing. With the packager, you (or the user) specify:
- What sessions to include: The packager will dynamically select sessions based on whether they match the product and application you specify and their status from a range of options.
- What to do with the package: It can be sent to your Loupe Server, emailed, or stored as a local file for you to subsequently handle on your own.
- Whether to mark sessions as read: Typically you'll want to include sessions only on one package so that if a user generates a new package later it won't contain sessions that have been completely sent before. With this option set, Loupe will mark all of the sessions that it includes in the package as long as the package is created successfully. If there is a problem creating the package no sessions will be marked as sent.
The packager then safely gathers all of the matching sessions into a single, highly compressed Package Repository File which is then sent to its destination.
How Sessions are Selected by the Packager
When creating a package, the Packager looks for sessions that are for a provided Product and optionally an Application within that Product. If you use the Packager or Packager Dialog by default the current Product will be used (without an application filter, so any session for any application associated with that product will be eligible to be included). Within that set of sessions, you have to specify additional criteria to tell the Packager what type of sessions you're interested in:
| Criterion |
Description |
| Completed Sessions |
Sessions that have completed executing, regardless of whether they exited normally or crashed. |
| Crashed Sessions |
Sessions that did not exit normally. |
| Active Session |
The currently executing application session (does not apply to Gibraltar.Package) |
| New Sessions |
Sessions that have never been sent before. |
| Critical Sessions |
Sessions with at least one log message with severity Critical |
| Error Sessions |
Sessions with at least one log message with severity Error |
| Warning Sessions |
Sessions with at least one log message with severity Warning. |
You can combine multiple criterion together with each adding all of the sessions that match. For example, adding Completed Sessions and Active Session gets all sessions that match either.
If you're trying to report a problem or issue from an application while it's still running you'll want to use the New Sessions and Active Session option. This will select every session that hasn't been successfully packaged previously and the current running session. This will provide you with all of the historical data you haven't seen before (providing a good background perspective on what the user has been experiencing) and their current situation up to the moment the packager is run.
Where can the Packager store the Session Data?
If you have configured a Loupe Server connection and the Server is available the user won't be prompted to select how to transport the data and the Server will be used.
Otherwise, The packager provides the user with three options:
- Send the sessions via email: The package will be attached to an email. A summary of the sessions will be written into the body of the email and a useful email subject line will be generated. The user can optionally provide a reply-to email address. To use this option, you (or the end user) will need to have configured email server information into the .NET configuration file.
- Send the sessions to a file: The package will be stored to a file name & path of your choosing.
- Send the sessions to removable media: This is a variation of sending to a file where the user selects just the removable media or network drive to store the sessions to and they are stored with a unique, descriptive package file name automatically. This is specifically designed to be useful in embedded systems or other scenarios where no Internet connection is available.
You can selectively disable these options by configuring the Loupe Agent which will affect how the Packager Dialog or Gibraltar.Package work. If you use the Packager class directly, the configuration options can be ignored. For more information on the configuration options available see Developer's Guide - Packager Configuration.
Where To Next?
See Also
Loupe Desktop
Developer's Guide
Reference