Skip to content

Lightrun CLI Commands

This reference describe the Lightrun CLI commands, options, and parameters.

Prerequisites

This tutorial assumes that you have:

Synopsis

java -jar lightrunc.jar <command> <options>

Add the -v command when running any command to enable the verbose mode. For exammple,

java -jar lightrunc.jar <command> <options> -v

Use java -jar lightrunc.jar help to view a list of all available commands and options in your terminal.

Example

$ java -jar lightrunc.jar help
Usage: LightrunC [OPTIONS]
Command line interface to Lightrun
      list-agents                 List the agents
      list-tags                   List the tags
      list-agents-by-tag <Tag>    List the agents by given tag
      list-actions <AgentId>      List the actions for the given agent id
      log <AgentId> <Filename>:<LineNumber> <Format> [-ignoreQuota] [-pipe 
        enable/disable/client]
                                  Insert a log to the given agent at the given
                                    file/line with the format (text of the log)
      clog <AgentId> <Filename>:<LineNumber> <Format> [-condition <Condition>] 
        [-expireSec <ExpireSec>] [-ignoreQuota] [-pipe enable/disable/client]
                                  Insert a conditional log to the given agent
                                    at the given file/line with the format
                                    (text of the log)
      snapshot <AgentId> <Filename>:<LineNumber> [-condition <Condition>] 
        [-watch <Expression>] [-expireSec <ExpireSec>] [-maxHitCount 
        <MaxHitCount>] [-ignoreQuota] [-pipe enable/disable/client]
                                  Insert a snapshot to the given agent at the
                                    given file/line
      counter <AgentId> <FileName>:<LineNumber> <CounterName> [-condition 
        <Condition>] [-expireSec <ExpireSec>] [-aggregateBy <Aggregate By 
        Prefix>] [ignoreQuota] [-pipe enable/disable/client]
                                  Count the number of times each thread hits
                                    the requested line.
                                  This option is currently supported only for
                                    Java agents.
      customMetric <AgentId> <FileName>:<LineNumber> <MetricName> 
        <MetricExpression> [-condition <Condition>] [-expireSec <ExpireSec>] 
        [-ignoreQuota] [-pipe enable/disable/client]
                                  Get metrics for the value given by the
                                    expression.
                                  This option is currently supported only for
                                    Java agents.
      set-value <AgentId> <FileName>:<LineNumber> <VarName1=VarValue> 
        [<VarName2=VarValue>...] [-condition <Condition>] [-expireSec 
        <ExpireSec>] [-ignoreQuota]
                                  Set the values of the given variables in a
                                    certain line.
                                  This option is currently supported only for
                                    Java agents.
      snapshot-data <AgentId> <SnapshotId> [<output-file>]
                                  Prints the accumulated data for a snapshot or
                                    saves it to <output-file>
      rm <AgentId> <ActionId>     Removes an action from the given agent
      rm-tag <tagName>            Removes a tag from the server
      status                      Prints the current status of the backend
      detach <on|off>             Disconnects all agents and disables lightrun
                                    instantly (when on) until it's turned off
                                    again
      print-logs <AgentId> [<ActionId>] [-range <StartTimestamp-EndTimestamp 
        (milliseconds)>]
                                  Print all logs for the given agent. Limited
                                    to 1000 most recent results. Optionally,
                                    you can specify the range via the 'range'
                                    argument
      print-all-logs              Print all logs for all agents. Limited to
                                    1000 most recent results. Optionally, you
                                    can specify the range via the 'range'
                                    argument
      enable-piping <AgentId>     Logs/Counters/TicTocs for this agent id will
                                    be piped to Lightrun's backend and printed
                                    on the server! Logs are available with the
                                    print-logs command.
      client-piping <AgentId>     Logs/Counters/TicTocs for this agent id will
                                    be piped to Lightrun's backend and hidden
                                    in the server! Logs are available with the
                                    print-logs command
      disable-piping <AgentId>    Logs/Counters/TicTocs for this agent id will
                                    only be printed on the server! (this
                                    doesn't stop the action)
      server-url <ServerURL>      Sets the server URL for the command line
      login                       Log in the server. The login will supply a
                                    URL for further authentication. Optionally,
                                    you can specify the user name and password
                                    via the 'email' and 'password' arguments.
      logout                      Logs out the currently logged in user on this
                                    machine
      version                     Prints the version of Lightrun CLI and the
                                    backend server
      listen                      Listens to agent/log registration events and
                                    prints them out
      -v, verbose                 Verbose mode
      user                        Prints the details on the server for the
                                    currently logged in user
      help                        Print help details
      toggle-action [AgentId] <ActionId>
                                  Enable/Disable an action
      add-certificate <Certificate>
                                  Add a server certificate
      show-certificates           Show all the server certificates
      rm-certificate <Certificate>
                                  Remove a server certificate
      enable-pinning-status       Enable certificate pinning
      disable-pinning-status      Disable certificate pinning
      get-pinning-status          Get certificate pinning
      clear-exceptions            Clear all exceptions from history by Admin /
                                    Manager
      ignoreQuota, -ignoreQuota   Add this argument when submitting a new
                                    action in order to disable the quota limits
                                    on that action. This operation can
                                    seriously impact your performance and is
                                    only available for users with the ignore
                                    quota permission
      -pipe enable/disable/client Set Piping for action.
                                  enable - enables piping in the backend.
                                  disable - Stops tracking action in the
                                    backend/client
                                  client - Action will be piped to the backend
                                    and hidden in the server

listen

The listen command prints out events (agent/actions events) from the server as they occur.

Synopsis

java -jar lightrunc.jar listen

Example

Note

Use Ctrl+C to exit listen mode.

Example

run java -jar lightrunc.jar listen

$ java -jar lightrunc.jar listen
Connecting to server
Listening for events
{"eventType":"CONNECTED","status":{"status":"OK","statusCode":"STATUS_OK"}}
{"eventType":"SESSION_DETAILS","metadata":{"sessionId":"ecf32a4b-43da-ea93-bce0-18ef235e962a"},"status":{"status":"OK","statusCode":"STATUS_OK"}}
{"agentDisplayName":"","eventType":"AUTHENTICATED","status":{"status":"OK","statusCode":"STATUS_OK"}}
{"actionType":"LOG","agentDisplayName":"erezk-Latitude-7400 (pid 30554)","agentId":"f4b0d260-ec00-4459-a9ed-b8ef7d4ffcf7","eventType":"LOG_DATA_ADDED","status":{"status":"OK","statusCode":"STATUS_OK"}}
{"actionType":"LOG","agentDisplayName":"erezk-Latitude-7400 (pid 30554)","agentId":"f4b0d260-ec00-4459-a9ed-b8ef7d4ffcf7","eventType":"LOG_DATA_ADDED","status":{"status":"OK","statusCode":"STATUS_OK"}}
{"actionType":"LOG","agentDisplayName":"erezk-Latitude-7400 (pid 30554)","agentId":"f4b0d260-ec00-4459-a9ed-b8ef7d4ffcf7","eventType":"LOG_DATA_ADDED","status":{"status":"OK","statusCode":"STATUS_OK"}}
{"actionType":"LOG","agentDisplayName":"erezk-Latitude-7400 (pid 30554)","agentId":"f4b0d260-ec00-4459-a9ed-b8ef7d4ffcf7","eventType":"LOG_DATA_ADDED","status":{"status":"OK","statusCode":"STATUS_OK"}}
{"actionType":"LOG","agentDisplayName":"erezk-Latitude-7400 (pid 30554)","agentId":"f4b0d260-ec00-4459-a9ed-b8ef7d4ffcf7","eventType":"LOG_DATA_ADDED","status":{"status":"OK","statusCode":"STATUS_OK"}}

version

The version command outputs information about your current CLI version and Lightrun server version.

Synopsis

java -jar lightrunc.jar version

Example

Example

run java -jar lightrunc.jar version

$ java -jar lightrunc.jar version
CLI Client Version: 1.4
Server Version: 1.6

user

The user command outputs all relevant information about the current logged-in user.

Synopsis

java -jar lightrunc.jar user

Example

Example

run java -jar lightrunc.jar user

$ java -jar lightrunc.jar user
class UserDTO {
    activated: true
    authorities: <permissions>
    company: class CompanyDTO {
        agentAPIKey: <agent-api-key>
        agentsEnabled: true
        certificatePinningEnabled: false
        displayName: null
        dontStorePluginToken: false
        id: <id>
        inviteKey: <invite-key>
        licenseExpiry: <liscense-expiry>
        licensedAgents: 1000
        licensedUsers: 1000
        managerId: null
        managerLogin: null
        name: <name>
        subscriptionStatus: STANDARD
        uniquifier: <uniquifier>
        users: []
    }
    companyName: <company-name>
    createdBy: <accout-created-by>
    createdDate: <created-date>
    email: <email>
    firstName: <first-name>
    id: <id>
    imageUrl: null
    langKey: en
    lastModifiedBy: <account-last-modified-by>
    lastModifiedDate: <last-modified-date>
    lastName: <last-name>
    password: null
    passwordHash: null
    passwordSet: false
    registerMethod: <register-method>
    subscriptionStatus: <subscription-status>
}

status

The status command outputs the current status of the Lightrun Management server, including licensing information about the agent and other relevant details.

Synopsis

java -jar lightrunc.jar status

Example

Example

run java -jar lightrunc.jar status

$ java -jar lightrunc.jar status
Lightrun CLI Client
----------
Server URL: https://app.lightrun.com
Company Name: <company-name
Version: 1.4
Backend Version: 1.6
User: <user-email>
Licenced Agents: 1000
Licence Expiry: <liscence-expiry>
Exception Daily Limit: Not Reached

detach

When experiencing any issues on the server, you might want to disable Lightrun in order to rule it out when troubleshooting.

The detach command allows you to disable all Lightrun agents on the specified server and re-enable the agents at will.

Synopsis

java -jar lightrunc.jar detach on/off

Options

Option Description
on Disable all Lightrun agents on your server.
off Enable detached agents.

Examples

Example

run java -jar lightrunc.jar detach on to disable all Lightrun agents

$ java -jar lightrunc.jar detach on
Agents are now detached

run java -jar lightrunc.jar detach off to enable all Lightrun agents

$ java -jar lightrunc.jar detach off
Agents are now re-enabled

logout

The logout logs out the currently logged in user from the Lightrun CLI.

Synopsis

java -jar lightrunc.jar logout

Example

Example

run java -jar lightrunc.jar logout

Logged out successfully!

agents and tags

list-agents

The list-agents command outputs all agents and their associated actions.

Synopsis

java -jar lightrunc.jar list-agents

Example

Example

run java -jar lightrunc.jar list-agents

$ java -jar lightrunc.jar list-agents
0 : ID e93fccd1-9f76-46ae-b703-056e25b8092e HOST ip-172-31-50-47 PID 14507 UPDATE 1/21/21, 9:16 AM
   ACTION 4261257f-fbc0-4fc5-8fe7-e8dbf3944eb7 FILE PrimeMainMR.java LINE 10 TYPE TICTOC
   ACTION 99e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION b383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION c3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE COUNTER
   ACTION e5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT
1 : ID f93fccd1-9f75-46ae-b703-456e25b8092e HOST ip-172-31-50-47 PID 14508 UPDATE 1/21/21, 9:16 AM
   ACTION 5261257f-fbc0-4fc5-8fe7-e8dbf3944eb7 FILE PrimeMainMR.java LINE 10 TYPE TICTOC
   ACTION 49e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION g383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION a3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE BREAKPOINT
   ACTION l5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT

list-agents-by-tag

The list-agents-by-tag command outputs all agents and actions related to the specified tag.

Synopsis

java -jar lightrunc.jar list-agents-by-tag Production

Options

Option Description
Tag The name of the relevant tag. For example, Production.

Example

Example

run java -jar lightrunc.jar list-agents-by-tag Production to list all agents associated to the Production tag.

$ java -jar lightrunc.jar list-agents-by-tag Production
0 : ID <user-id> HOST <host> PID 10 UPDATE 7/26/22, 8:08 PM TAGS [Production]
 downloads % java -jar lightrunc.jar list-agents-by-tag Production
0 : ID <user-id> HOST <host> PID 10 UPDATE 7/26/22, 8:13 PM TAGS [Production]
 ACTION 1ecff847-db90-46f8-9493-bdac3518809b FILE PrimeMainMR.java LINE 30 TYPE LOG Hello world {expression}
 ACTION 275cae4c-ece9-4f6c-8950-594cd3ccc7fd FILE PrimeMainMR.java LINE 59 TYPE COUNTER 
 ACTION 5eaeeca1-4861-473b-8d55-b39b29af26ad FILE PrimeMainMR.java LINE 20 TYPE TICTOC ERROR Collision in breakpoint location on the same tree
 ACTION 758a36b8-50be-472c-8a6e-891eb3d31747 FILE PrimeMainMR.java LINE 78 TYPE BREAKPOINT 
 ACTION a214a929-6bc8-44ff-92f1-5c0140084038 FILE PrimeMainMR.java LINE 33 TYPE LOG Hello world {expression}

list-tags

The list-tags command lists all tags and their actions.

Synopsis

java -jar lightrunc.jar list-tags

Example

Example

run java -jar lightrunc.jar list-tags

$ java -jar lightrunc.jar list-tags
Tag: Production
   ACTION 4f6f8e67-2252-4093-bcf2-9a5254f074ef FILE PrimeMainMR.java LINE 50 TYPE LOG Hello world {java expression}
   ACTION 99e8e7b0-9248-4d89-8f6f-2d3c5fa9aebc FILE PrimeMainMR.java LINE 15 TYPE LOG Hello world {java expression}gg
   ACTION e5790c99-f763-4d26-8d3f-2714c89c0fad FILE PrimeMainMR.java LINE 10 TYPE BREAKPOINT
Tag: Staging
   ACTION b383e31b-8749-419f-a492-85a919cc0da8 FILE PrimeMainMR.java LINE 22 TYPE TICTOC
   ACTION c3f863e6-ba7d-4480-83c0-ef4a278ecddb FILE PrimeMainMR.java LINE 15 TYPE COUNTER

list-actions

The list-actions command lists all actions associated with a specified agent or tag.

Synopsis

java -jar lightrunc.jar list-actions <AgentId>

Options

Option Description
Agent-ID Enter the ID of the relevant agent.
Tag Enter the relevant tag instead of an agent ID.

Examples

Example

run java -jar lightrunc.jar list-actions <AgentId> to list all actions associated with the specified agent.

$ java -jar lightrunc.jar list-actions 7b5a1f54216b  
There are no actions to agent 7b5a1f54216b

run java -jar lightrunc.jar list-actions tag:<tagName> to list all actions associated with the specified tag.

$  java -jar lightrunc.jar list-actions tag:Production
There are no actions to agent tag:Production

client-piping

The client-piping command pipes Log, Metrics, Counters, and Tic Toc data to the Lightrun Console, Management Portal, and any other configured logging tool.

Synopsis

java -jar lightrunc.jar client-piping <Agent-ID>

Options

Option Description
Agent-ID Enter the ID of the relevant agent.

Example

Example

run java -jar lightrunc.jar client-piping <Agent-ID>

$ java -jar lightrunc.jar client-piping da0c440b-ae8e-4011-9f61-93a07405baa2
Log tracking in progress, use print-logs to view the output

enable-piping

The enable-piping command pipes Log, Metrics, Counters, and Tic Toc data to the Lightrun Console, Management Portal, and any other configured logging tool.

Synopsis

java -jar lightrunc.jar enable-piping <Agent-ID>

Options

Option Description
Agent-ID Enter the ID of the relevant agent.

Example

Example

run java -jar lightrunc.jar enable-piping <Agent-ID>

$ java -jar lightrunc.jar enable-piping da0c440b-ae8e-4011-9f61-93a07405baa2
Log tracking in progress, use print-logs to view the output

disable-piping

The disable-piping command disables all output piping for the specified agent.

Synopsis

java -jar lightrunc.jar disable-piping <Agent-ID>

Options

Option Description
Agent-ID Enter the ID of the relevant agent.

Example

Example

run java -jar lightrunc.jar disable-piping <Agent-ID>

$ java -jar lightrunc.jar disable-piping da0c440b-ae8e-4011-9f61-93a07405baa2 
Log tracking is disabled

actions

toggle-action

The toggle-action command enables or disables an action.

Synopsis

java -jar lightrunc.jar toggle-action <Agent-ID> <ActionId>

Options

Option Description
Agent-ID Enter the ID of the relevant agent.
Action-ID Enter the ID of the relevant action.

Examples

Example

run java -jar lightrunc.jar toggle-action <Agent-ID> <ActionId> on an active action to disable the action.

$ java -jar lightrunc.jar toggle-action da0c440b-ae8e-4011-9f61-93a07405baa2  b5f20e04-5ab1-4c14-887b-1386ee96ce1b
Action b5f20e04-5ab1-4c14-887b-1386ee96ce1b was successfully disabled

run java -jar lightrunc.jar toggle-action <Agent-ID> <ActionId> on a disabled action to enable the action.

$ java -jar lightrunc.jar toggle-action da0c440b-ae8e-4011-9f61-93a07405baa2  b5f20e04-5ab1-4c14-887b-1386ee96ce1b
Action b5f20e04-5ab1-4c14-887b-1386ee96ce1b was successfully enabled

logs

The logs command inserts a log to the given agent at the given file/line with the format (text of the log).

Synopsis

java -jar lightrunc.jar log <AgentId> <Filename>:<LineNumber> <Format> -expireSec <ExpireSec> [-ignoreQuota]

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.

Options

Option Description
Agent-ID The ID of the relevant agent.
Change AgentID to tag:tagName to insert the action into a tag.
Filename The name of the file, including the suffix
LineNumber The number of the line of code in the referenced file.
Format The text to appear in your logs.
expireSec The amount of time for which this log should run.
Dynamic logs timeout after 1 hour by default if you don't insert an expiry time.
ignoreQuota When set, the quota limit configured for running Lightrun actions is overridden and this log will continue to run even if it reaches the quota.
Only users with the Ignore Quota role can use this option.

Example

Example

  • run java -jar lightrunc.jar log <AgentId> <Filename>:<LineNumber> <Format> -expireSec <ExpireSec> [-ignoreQuota] to add a log to an agent.
    $ java -jar lightrunc.jar log 00e5ab81-2d63-404f-9c27-2f7ee9a0bfb8 request.js:11 Hello-world  -expireSec 360 
    The log was submitted
    
  • run java -jar lightrunc.jar log tag:<tagName> <Filename>:<LineNumber> <Format> -expireSec <ExpireSec> [-ignoreQuota] to add a log to a set of agents identified by a tag.
    $ java -jar lightrunc.jar log tag:Production request.js:11 Hello-world  -expireSec 360 
    The log was submitted
    

The print-logs command outputs all logs for the given agent.

Synopsis

java -jar lightrunc.jar print-logs <AgentId> [<ActionId>] [-range <StartTimestamp-EndTimestamp (milliseconds)>]

Note

  • Piping must be enabled (enable-piping command) for the print-logs to be able to output.
  • The print-logs output is limited to 1000 most recent results.

Options

Option Description
AgentId The ID of the relevant agent.
ActionId The ID of the action for which you want to view all logs. You can run 'list-actions' to view a list of action IDs.
range Specify a time range to view dynamic logs for only that period of time. Use 13 digit epoch time when specifying a range.

Example

Example

run java -jar lightrunc.jar print-logs <AgentId> [<ActionId>] [-range <StartTimestamp-EndTimestamp (milliseconds)>]

$ java -jar lightrunc.jar print-logs 0 0 -range 1615391135824-1615391135924
INFO: LOGPOINT: 197581639 is a prime number
INFO: LOGPOINT: 197581649 is a prime number
INFO: LOGPOINT: 197581651 is a prime number
INFO: LOGPOINT: 197581673 is a prime number
INFO: LOGPOINT: 197581687 is a prime number
INFO: LOGPOINT: 197581697 is a prime number
INFO: LOGPOINT: 197581717 is a prime number
INFO: LOGPOINT: breakpointId: [f188655e-7dab-42a1-acad-ce53a16a85dc]: Logpoint is paused due to high call rate until log quota is restored

The print-all-logs command prints all logs for all agents.

Synopsis

java -jar lightrunc.jar print-all-logs

Note

  • Piping must be enabled (enable-piping command) for the print-all-logs to be able to output.
  • The print-all-logs output is limited to 1000 most recent results.

Example

Example

run java -jar lightrunc.jar print-all-logs

$ java -jar lightrunc.jar print-all-logs
INFO: LOGPOINT: breakpointId: [786e3a7e-a60b-4e48-884e-2c126c4da8e3]: Logpoint is paused due to high call rate until log quota is restored
INFO: LOGPOINT: Hello world 24373299
INFO: LOGPOINT: Hello world 24373300
INFO: LOGPOINT: Hello world 24373301
INFO: LOGPOINT: Hello world 24373298
INFO: LOGPOINT: Hello world 24373307
INFO: LOGPOINT: Hello world 24373308
INFO: LOGPOINT: Hello world 24373309
INFO: LOGPOINT: Hello world 24373310
INFO: LOGPOINT: Hello world 24373312

clog

The clog command inserts a conditional log for the given agent in the given file and line.

Synopsis

java -jar lightrunc.jar clog <AgentId> <Filename>:<LineNumber> <Format> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota]

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.

Options

Option Description
Agent-ID The ID of the relevant agent.
Change AgentID to tag:tagName to insert the action into a tag.
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.
Format The text to appear in your dynamic logs for this metric.
Condition Any valid Java expression that does not change the state of the code.
ExpireSec The amount of time for which this log should run.
ignoreQuota When set, the quota limit configured for running Lightrun actions is overridden and this log will continue to run even if it reaches the quota.
Only users with the Ignore Quota role can use this option.

Example

Example

  • run java -jar lightrunc.jar clog <AgentId> <Filename>:<LineNumber> <Format> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota] to add the clog to an agent.
    java -jar lightrunc.jar clog 5c6e9cdef4e833279ee286a1 Main.java:10 "Array size {arr.length}" -condition "i % 10 == 0""
    
    The log will be printed when the expression i % 10 == 0 evaluates to true.
  • run java -jar lightrunc.jar clog tag:<tagName> <Filename>:<LineNumber> <Format> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota] to add a clog to a set of agents identified by a tag.
    java -jar lightrunc.jar clog tag:Production Main.java:10 "Array size {arr.length}" -condition "i % 10 == 0""
    
    The log will be printed when the expression i % 10 == 0 evaluates to true.

snapshot

The snapshot command inserts a snapshot to the specified agent at the given file/line.

Synopsis

java -jar lightrunc.jar snapshot <AgentId> <Filename>:<LineNumber> [-condition <Condition>] [-expireSec <ExpireSec>] [-maxHitCount <MaxHitCount>] [-ignoreQuota]

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.

Options

Option Description
Agent-ID The ID of the relevant agent.
Change AgentID to tag:tagName to insert the action into a tag.
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.
Condition Any valid Java expression that does not change the state of the code.
ExpireSec The amount of time for which this action should run.
MaxHitCount The maximum number of times to take this snapshot during the valid period of this action; default = 1
ignoreQuota When set, the quota limit configured for running Lightrun actions is overridden and this action will continue to run even if it reaches the quota.
Only users with the Ignore Quota role can use this option.

Example

Example

  • run java -jar lightrunc.jar snapshot <AgentId> <Filename>:<LineNumber> [-condition <Condition>] [-expireSec <ExpireSec>] [-maxHitCount <MaxHitCount>] [-ignoreQuota] to add a snapshot to an agent.
    $ java -jar lightrunc.jar snapshot da0c440b-ae8e-4011-9f61-93a07405baa2 PrimeMainMR.java:42 
    The breakpoint was submitted
    
  • run java -jar lightrunc.jar snapshot tag:<tagName> <Filename>:<LineNumber> [-condition <Condition>] [-expireSec <ExpireSec>] [-maxHitCount <MaxHitCount>] [-ignoreQuota] to add a snapshot to a set of agents identified by a tag.
    $ java -jar lightrunc.jar snapshot tag:Production PrimeMainMR.java:42 
    The breakpoint was submitted
    

snapshot-data

The snapshot-data command prints out the accumulated data for a snapshot, or save the data into a specified output file.

Synopsis

java -jar lightrunc.jar snapshot-data <AgentId> <SnapshotId>[<output-file>]

Options

Option Description
Agent-ID The ID of the relevant agent.
SnapshotId The ID of the snapshot for which to print the existing data.

Example

Example

run java -jar lightrunc.jar snapshot-data <AgentId> <SnapshotId>[<output-file>]

$ java -jar lightrunc snapshot-data e178578f-14da-476f-a084-bc460d6ec2b0 eb5abb0a-4677-4bed-9999-ea0b76c4efd2

[class BreakpointDataDTO {
 actionId: eb5abb0a-4677-4bed-9999-ea0b76c4efd2
 agentId: e178578f-14da-476f-a084-bc460d6ec2b0
 createTime: class TimeDTO {
     nanos: 696685698
     seconds: 1611590801
 }
 dataId: 72f81a80-c415-4f00-a43d-83523a735230
 evaluatedExpressions: null
 stackFrames: [class AgentStackFrameDTO {
     arguments: [class WatchEntryDTO {
         members: null
         name: args
         status: null
         type: null
         value: null
         varTableIndex: 1
     }]
     function: PrimeMain.main
     locals: [class WatchEntryDTO {
         members: null
         name: i
         status: null
         type: int
         value: 30514481
         varTableIndex: null
     }]
     location: class LocationDTO {
         column: 0
         endOfLine: false
         line: 20
         path: PrimeMain.java
     }
 }]
 variableTable: [class WatchEntryDTO {
     members: null
     name: null
     status: class BreakpointStatusDTO {
         description: class BreakpointStatusDescriptionDTO {
             format: Buffer full. Use an expression to see more data
             parameters: null
         }
         isAccepted: false
         isError: true
         refersTo: VARIABLE_VALUE
     }
     type: null
     value: null
     varTableIndex: null
 }, class WatchEntryDTO {
     members: [class WatchEntryDTO {
         members: null
         name: length
         status: null
         type: int
         value: 0
         varTableIndex: null
     }]
     name: null
     status: null
     type: java.lang.String[]
     value: null
     varTableIndex: null
     }]
}]

Tip

You may use agent/action indexes instead of an ID. For example:

java -jar lightrunc.jar snapshot-data 0 0 will output the first snapshot of the first agent

Tip

The output file is saved in JSON format, and can be manipulated by other tools.

customMetric

The customMetric command creates a custom metric based on specified expressions and values

Note

  • This command is currently supported only for Java agents.
  • Always use quotes when setting a condition ("num>3") in order to avoid shell output redirection to file descriptor 3.

Synopsis

java -jar lightrunc.jar customMetric <AgentId> <FileName>:<LineNumber> <MetricName> <MetricExpression> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota]

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.

Options

Option Description
ignoreQuota 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. The quota controls use of CPU, Networking, Memory, excessively long strings, too many instructions printing out, protection from infinite loops and the like.
Only administrators with the Ignore Quota role can use this option.
Agent-ID The ID of the relevant agent. Change AgentID to tag:tagName to insert the action into a tag.
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.
MetricName Assign a unique name to this metric.
MetricExpression Configure any valid Java expression that does not change the state of the code.
Condition Any valid Java expression that does not change the state of the code.
ExpireSec Configure the duration that this metric should run in seconds.

Example

Example

  • run java -jar lightrunc.jar customMetric <AgentId> <FileName>:<LineNumber> <MetricName> <MetricExpression> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota] to add a customMetric to an agent.
    $ java -jar lightrunc.jar customMetric 0 PrimeMain.java:14 MyPrimeMetric num -condition "num>3"
    INFO: 10 Mar 2021, 11:59:26 CustomMetric Stats:
    {
        "MyPrimeMetric" :
        {"count" : 55106,"max" : 675526339,"mean" : 6.731275234790297E8,"min" : 629652109,"p50" : 6.73885867E8,"p75" : 6.74822641E8,"p95" : 6.75395141E8,"p98" : 6.75455779E8,"p99" : 6.75491381E8,"p999" : 6.75526339E8,"stddev" : 2424070.6627122667  }
    }
    
  • run java -jar lightrunc.jar customMetric tag:<tagName> <FileName>:<LineNumber> <MetricName> <MetricExpression> [-condition <Condition>] [-expireSec <ExpireSec>] [-ignoreQuota] to add a customMetric to a set of agents identified by a tag.
    $ java -jar lightrunc.jar customMetric tag:Production PrimeMain.java:14 MyPrimeMetric num -condition "num>3"
    INFO: 10 Mar 2021, 11:59:26 CustomMetric Stats:
    {
        "MyPrimeMetric" :
        {"count" : 55106,"max" : 675526339,"mean" : 6.731275234790297E8,"min" : 629652109,"p50" : 6.73885867E8,"p75" : 6.74822641E8,"p95" : 6.75395141E8,"p98" : 6.75455779E8,"p99" : 6.75491381E8,"p999" : 6.75526339E8,"stddev" : 2424070.6627122667  }
    }
    

counter

The counter command returns the number of times each thread hit the specified code line.

Note

  • This command is currently supported only for Java agents.

Synopsis

java -jar lightrunc.jar counter <AgentId> <FileName>:<LineNumber> <CounterName> [-condition <Condition>] [-expireSec <ExpireSec>] [-aggregateBy <Aggregate By Prefix>] [ignoreQuota]

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.

Options

Option Description
Agent-ID The ID of the relevant agent. Change AgentID to tag:tagName to insert the action into a tag.
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.
CounterName The name of the counter - the text to appear in your dynamic logs for this metric.
Condition Any valid Java expression that does not change the state of the code.
ExpireSec The amount of time for which this counter should run.
aggregateBy Collect and aggregate data for the specified string only.
ignoreQuota Only users with the Ignore Quota role can use this option. When set, the quota limit configured for running Lightrun actions is overridden and this counter will continue to run even if it reaches the quota.

Example

Example

  • run java -jar lightrunc.jar counter <AgentId> <FileName>:<LineNumber> <CounterName> [-condition <Condition>] [-expireSec <ExpireSec>] [-aggregateBy <Aggregate By Prefix>] [ignoreQuota] to add a counter to an agent.
    $ java -jar lightrunc counter e178578f-14da-476f-a084-bc460d6ec2b0 PrimeMain.java:20 myCounter
    The counter was submitted
    
  • run java -jar lightrunc.jar counter tag:<tagName> <FileName>:<LineNumber> <CounterName> [-condition <Condition>] [-expireSec <ExpireSec>] [-aggregateBy <Aggregate By Prefix>] [ignoreQuota] to add a counter to a set of agents identified by a tag.
    $ java -jar lightrunc counter tag:Production PrimeMain.java:20 myCounter
    The counter was submitted
    

certificates

show-certificates

The show-certificates command outputs all certificates present in your Lightrun server.

Synopsis

java -jar lightrunc.jar show-certificates

Example

Example

run java -jar lightrunc.jar show-certificates

$ java -jar lightrunc.jar show-certificates
ee80811b38e7e6c2dc4cc372cbea86bd86b446b012e427f2e19bf094afba5d12 (PRECONFIGURED)

add-certificate

The add-certificate command adds a new certificate to the Lightrun server.

Synopsis

java -jar lightrunc.jar add-certificate <certificate-sha256-public-key>

Options

Option Description
<certificate-sha256-public-key> sha256 of the public key of the certificate

Example

Example

run java -jar lightrunc.jar add-certificate <certificate-sha256-public-key> to add a new cerficate.

$ java -jar lightrunc.jar add-certificate <certificate-sha256-public-key>
Successfully added certificate.

rm-certificate

The rm-certificate command removes a certificate from the Lightrun server.

Synopsis

java -jar lightrunc.jar rm-certificate <certificate-sha256-public-key>

Options

Option Description
<certificate-sha256-public-key> sha256 of the public key of the certificate

Example

Example

run java -jar lightrunc.jar rm-certificate <certificate-sha256-public-key> to remove a cerficate from the Lightrun server.

$ lightrunc.jar rm-certificate <certificate-sha256-public-key>
Successfully removed certificate <certificate-sha256-public-key>

get-pinning-status

The get-pinning-status command returns the Lightrun server certificate pinning status.

Synopsis

java -jar lightrunc.jar get-pinning-status

Example

Example

run java -jar lightrunc.jar get-pinning-status.

$ java -jar lightrunc.jar get-pinning-status
Pinning status is disabled

enable-pinning-status

The enable-pinning-status command enables certificate pinning.

Synopsis

java -jar lightrunc.jar enable-pinning-status

Example

Example

run java -jar lightrunc.jar enable-pinning-status

$ java -jar lightrunc.jar enable-pinning-status
Certificate pinning is now enabled

disable-pinning-status

The disable-pinning-status command disables certificate pinning.

Synopsis

java -jar lightrunc.jar disable-pinning-status

Example

Example

run java -jar lightrunc.jar disable-pinning-status

$ java -jar lightrunc.jar disable-pinning-status
Certificate pinning is now disabled

Last update: December 4, 2022