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¶
To use the Lightrun CLI
Prerequisites
Sign up for your Lightrun account before getting started.
The Lightrun CLI requires Java be installed.
-
Log in to your Lightrun account from the browser and navigate to Getting Started.
-
Download 'lightrunc.jar' from the landing page from the Command Line Tool section.
-
Open the terminal and navigate to where you downloaded the file.
-
Authenticate your CLI with your Lightrun account:
-
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 -
Copy and run the second command line that appears in your browser.
Example
java -jar lightrunc.jar login myaccount@acme.com
-
-
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