Skip to content

Administration from the terminal

From the terminal, managers can:

Note

The commands described here can only be performed by a user with the Manager role.

Important

If the file name and line number don't match the bytecode version of the app, Lightrun will behave inconsistently and will most likely fail.

Set up your CLI

  1. Install the CLI

  2. Authenticate the CLI

To use the Lightrun CLI

Prerequisites

Sign up for your Lightrun account before getting started.

The Lightrun CLI requires Java be installed.

  1. Log in to your Lightrun account from the browser and navigate to Getting Started.

  2. Download 'lightrunc.jar' from the landing page from the Command Line Tool section.

  3. Open the terminal and navigate to where you downloaded the file.

  4. Authenticate your CLI with your Lightrun account:

    1. Copy and run the first command line that appears in your browser.

      Example

      java -jar lightrunc.jar server-url https://2147483647.lightrun.com/company/acme

    2. Copy and run the second command line that appears in your browser.

      Example

      java -jar lightrunc.jar login myaccount@acme.com

  5. To run any Lightrun command, add the following prefix:

    java -jar lightrunc.jar
    
Authenticate the CLI with Lightrun

To use the CLI, first authenticate with your Lightrun account. You can authenticate directly from within the CLI or choose to redirect to the browser.

lightrunc.jar login <username/email address/password>

Example

Log in directly from the CLI:

java -jar lightrunc.jar login -email jane.doe@example.com -password secretpassword

Example

Log in with a redirect to your browser:

java -jar lightrunc.jar login myaccount@acme.com

Administrator commands

create-user

Description

create-user creates a new user based on the specified details.

Synopsis

lightrunc.jar create-user <Username> <FirstName> <LastName> <Email> <Role1> <Role2>...

Options

Option Description
Username A unique name for the user
Email A valid and unique email address
Role Valid values:
ROLE_ADMIN
ROLE_MANAGER
ROLE_USER
ROLE_AGENT

Note

Only the administrator is authorized to create a user with ROLE_AGENT.

Example

The following creates a new user with the User role for Jane Doe with the user name newuser1 when a Manager from the company YourCompany runs the command.

java jar lightrunc.jar create-user newuser1 Jane Doe jane@yourcompany.com ROLE_USER

When you press Enter, the terminal requests a password for the new user.

Enter a password, press Enter and the terminal prints:

User successfully created in company YourCompany

delete-user

Description

Delete a specified user.

Note

The user must first be deactivated before they can be deleted. Deactivate directly from the app by navigating to Manager->User management.

Synopsis

java jar lightrunc.jar delete-user <user name>

Options

  • user name - the user name for the user to be deleted

Output and examples

Example

lightrunc.jar delete-user SMITHJ

​ The following is printed in the terminal: ​

 `User Deleted`

set-value

Description

Administrators with the Set Value role can insert Lightrun actions with conditions that change the values of specified variables in your code.

Synopsis

lightrunc.jar set-value <AgentId> <FileName>:<LineNumber> -expireSec <VarName1=VarValue> <VarName2=VarValue>…​

Options

Option Description
Agent-ID Enter the ID of the relevant agent
FileName The name of the file containing the code in which to add the metric, including the extension. For example: MyJavaFile.java
LineNumber The line number within the code file
VarName Any valid Java expression, including functions
Condition Any valid Java expression, including functions
ExpireSec Configure the duration that this metric should run in seconds
ignoreQuota Only administrators with the Ignore Quota role can use this option. When set, the quota limit configured for running Lightrun actions is overridden and this custom metric will continue to run even if it reaches the quota.

Output and examples

lightrunc set-value <AgentId> <FileName>:<LineNumber> -expireSec <VarName1=VarValue> <VarName2=VarValue>…​

clear-exceptions

Description

Clear all exceptions from history.

Synopsis

lightrunc clear-exceptions

Options

None

Output and examples

The following output is printed:

Successfully cleared exceptions history from the server

Agent properties

Agent configurations can be changed with a command line argument.

The command line arguments should be inserted after the path of the agent and they should be separated by a comma.

Synopsis

-agentpath:<path-to-agent>/lightrun_agent.so=--<parameter>=<value>,--<parameter>=<value>...

Agent parameters

Following are the parameters that can be configured from the terminal.

Parameter name Explanation Type
hub_retry_delay_ms amount of time in milliseconds to sleep before retrying failed requests to Management server int32
debuggee_disabled_delay_ms amount of time in milliseconds to sleep before checking whether the debugger was enabled back int32
lightrun_extra_class_path additional directories and files containing resolvable binaries string
lightrun_init_wait_time_ms timeout for wait iflightrun_wait_for_init is set int32
lightrun_wait_for_init ck application until first time of fetching breakpoints from the server bool
enable_safe_caller allows any method without side effects in expressions bool
extra_blocked_methods additional methods to block for testing purposes string
extra_allowed_methods additional methods allowed for testing purposes string
extra_whitelisted_classes internal names of additional classes to allow for testing purposes string
expression_max_classes_load_quota maximum number of classes that the Nano Java interpreter is allowed to load while evaluating a single breakpoint expression int32
expression_max_interpreter_instructions_quota maximum number of instructions that the Nano Java interpreter is allowed to execute while evaluating a single breakpoint expression int32
pretty_printers_max_classes_load_quota maximum number of classes that the Nano Java interpreter is allowed to load while formatting some well known data structures int32
pretty_printers_max_interpreter_instructions_quota maximum number of instructions that the Nano Java interpreter is allowed to execute while formatting some well-known data structures int32
dynamic_log_max_classes_load_quota maximum number of classes that the Nano Java interpreter is allowed to load while evaluating all expressions in a single dynamic log statement int32
dynamic_log_max_interpreter_instructions_quota maximum number of instructions that the Nano Java interpreter is allowed to execute while evaluating all expressions in a single dynamic log int32
safe_caller_max_array_elements maximum allowed size of the array to copy or allocate in safe caller (copying or allocating larger arrays is considered to be too expensive MISSING int32
safe_caller_max_interpreter_stack_depth maximum stack depth that safe caller will allow int32
cdbg_description_suffix additional text to be appended to debug description string
cdbg_class_files_cache_size cache size for class files used in safe method caller int32
cdbg_max_instructions_high use this value when ignoring quota int32
cdbg_max_stack_depth maximum number of stack frames to unwind int32

Example

-agentpath:<pathtoagent>/lightrun_agent.so=--enable_safe_caller,--lightrun_init_wait_time_ms=999

Last update: April 8, 2021