Raygun CLI

Raygun APM configuration using the CLI tool rgc.exe

The Raygun CLI tool is installed with all Raygun APM installations and can be used to register the agent and configure applications from a command line interface such as CMD or PowerShell.

The CLI tool by default can be located at %ProgramFiles(x86)%\Raygun\RaygunAgent\rgc.exe

Registration commands

Register

Registers a newly installed Raygun APM Agent with Raygun and configure the default API key. This needs to be performed once for each new installation.

# Register the Agent
> rgc.exe -register <API-KEY>

Deregister

Deregisters the Raygun APM Agent with Raygun. This should be performed before uninstalling the agent or if you want to temporarily stop sending trace data to Raygun.

# Deregister the Agent
> rgc.exe -deregister

Application commands

Enable

Enables profiling of a process by specifying the process identifier. This commands should be performed for each IIS application pool that you want to enable profiling for.

# Enable profiling an IIS application with minimum parameters
> rgc.exe -enable <raygun.com.apppool> -type IIS

# Enable profiling an IIS application with all optional parameters
# -apikey    : Specify a non-default API key for this application
# -startup   : Specify a profiler startup period in seconds
# -debugmode : Enable debug mode for the application for detailed diagnostics
# -norecycle : Don't recycle the IIS application pool after applying changes (you will need to recycle via another method)
> rgc.exe -enable <raygun.com.apppool> -type IIS -apikey <APP-API-KEY> -startup 60 -debugmode -norecycle

Disable

Disables profiling of a process by specifying the process identifier. This commands should be performed when you want to stop profiling an IIS application.

# Disable profiling an IIS application with minimum parameters
> rgc.exe -disable <raygun.com.apppool> -type IIS

# Disable profiling an IIS application with all optional parameters
# -norecycle : Don't recycle the IIS application pool after applying changes (you will need to recycle via another method)
> rgc.exe -disable <raygun.com.apppool> -type IIS -norecycle

Diagnostic commands

Status

Runs status checks against the Raygun APM Agent. This command will do some basic checks with the Agent to check for connectivity issues and API key validity.

# Run basic status checks
> rgc.exe -status

# Outputs
# Agent status: Registered
# Agent test: Connected to the Raygun Agent v1.0.0 on port 2790.
# API test: Connected to the Raygun API at https://api2.raygun.com.
# API key test: API key <API-KEY> is valid
# Profiler x86 test: 32-bit Profiler found at C:\Program Files (x86)\Raygun\RaygunProfiler\1.0.0\x86\RaygunProfiler.dll.
# Profiler x64 test: 64-bit Profiler found at C:\Program Files\Raygun\RaygunProfiler\1.0.0\x64\RaygunProfiler.dll.

Auto diagnostic

Starts a diagnostic session that runs for a limited time period. Once complete it will automatically upload the diagnostic session to Raygun. Note that debug mode should be enabled for an application being profiled for this to be useful.

# Run an auto diagnostic session that is uploaded to Raygun when complete
> rgc.exe -auto-diagnostic

# You can also run it with a defined time period, specified in seconds
> rgc.exe -auto-diagnostic 120

Start diagnostic

Starts a diagnostic session that runs for a limited time period. Once complete it will remain on disk allowing you to view the data collected before uploading it to Raygun. Note that debug mode should be enabled for an application being profiled for this to be useful.

# Run a diagnostic session that runs for a defined time period, specified in seconds
> rgc.exe -start-diagnostic 120

List diagnostics

List diagnostics sessions stored on disk. This can be used to get the session id or number to be used to upload or delete a diagnostic session. Note that diagnostic sessions by default are stored in %Temp%\RaygunDiagnostics\

# List all diagnostic sessions
> rgc.exe -list-diagnostics

Upload diagnostic

Uploads a diagnostic session to Raygun. The session id or number used by this command can be determined by running the -list-diagnostics command. Once a session has been successfully uploaded it will be deleted from disk.

# Upload a diagnostic session to Raygun using the session id
> rgc.exe -upload-diagnostic ca2b1878

# You can also upload the latest session not specifying a session id or number
> rgc.exe -upload-diagnostic

Delete diagnostic

Deletes a diagnostic session from disk. This command is used to delete a diagnostic session from disk that you don't want to upload. The session id or number used by this command can be determined by running the -list-diagnostics command.

# Delete a diagnostic session using the session id
> rgc.exe -delete-diagnostic ca2b1878

Agent tail

Starts a tail session for the profiler agent data stream. This is useful for debugging trace data being sent from the profiler to the agent.

# Run a profiler agent data tail
> rgc.exe -agenttail

Profiler tail

Starts a tail session for the profiler log stream. Note that debug mode will need to be enabled for an application being profiled for this to work. This is useful for debugging the internals of the profiler.

# Run a profiler log tail
> rgc.exe -profilertail

Debug dump

Sends a command to the Raygun APM Agent to trigger a debug dump of data it is currently processing. This will then automatically be uploaded to Raygun for analysis. This command should only be used if you are experiencing high memory usage on the Raygun Agent process and would like Raygun support to determine why. After successfully running this command, please contact Raygun support to let them know you have triggered the dump along with a description of the issue.

# Trigger an agent debug dump that is uploaded to Raygun
> rgc.exe -debugdump

Exit codes

  • 0 = Success
  • 1 = General error
  • 2 = No user permissions, must be run with a priveledged user account
  • 10 = Invalid parameter value
  • 20 = Specified process type cannot be profiled
  • 30 = Specified process identifier was not found
  • 40 = Could not connect to the Raygun Agent, check that it is running
  • 50 = Could not connect to the Raygun API, check connectivity to the internet, specifically api.raygun.com
  • 60 = Not authorized when connecting to the Raygun API, specified API key is invalid

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.