# yc-360 Script Action API

Using 'action' API, one can trigger the yc-360 script from a remote location. When triggered, the yc-360 script will capture 360-degree artifacts (i.e., GC logs, thread dumps, heap dumps, top, netstat, ...) from the target application and transmit them to the yCrash server to do root cause analysis.

This API will be handy for integration with monitoring tools (Cloud Watch, New Relic, App Dynamics, Dynatrace,...). These Monitoring tools are good at detecting and alerting performance degradations (such CPU spikes, poor response times, memory consumption increase). When these alerts are generated, you can trigger the 'action' API.

# How to invoke Action API?

To invoke 'action' API, you need to follow two simple steps:

Activate 'action API' in yc-360 script
Invoke API

# 1. Activate 'action API' in yc-360 script

In order to invoke 'action API' in the yc-360 script, first you need to activate this API in the yc-360 script. It can be activated by following the steps given here.

# 2. Invoke API

Action API can be invoked from the remote location using the below-given end-point and payload.

# End-point

'action' API can be invoked in the following end-point.

http://host:port/action

'host' - is the host address where yc-360 script is running.

'port' - is the port in which yc-360 script is listening. You can configure the port in which yc-360 script should listen by passing the '-port' argument to the yCrash config file.

# Request Payload

Make HTTP POST to above end-point with the following request payload:

{
   "key": "buggycompany@aeiou-c3eb-4c9a-8254-f00dist0eat", 
   "actions": ["capture 16036"],
   "waitFor": true
}

1
2
3
4
5
6

Here is the description of request payload elements:

Element	Description
key	Unique key that 'action API' uses for authentication. Use the same yc-360 script key that is provided to you at the time of registration
actions	If you want to capture the artifacts and do the root cause analysis on the application whose process id is 16036, then you will pass the command ["capture 16036"]. If you want to do root cause analysis on multiple processes, you can pass multiple process tokens. Example: ["capture 16036", "capture 5236", "capture 6139"]. If you don't know process Id, you can pass a token which can uniquely identify a process. For more details about Process tokens, refer to the 'Identifying process' section given below. In Dashboard if you would like to set application name to the incident, you can pass the application name to the ‘capture’ element after ‘$’ sign. Example: ["capture 16036$myAppName-1", "capture 5236$myAppName-2", "capture 6139$myAppName-3"]
waitFor	This element is optional. When you pass this element with value 'true', then yc-360 script will wait until all artifacts are captured and transmitted to the server. If this flag is not passed or passed with value 'false', then the yc-360 script will immediately respond back to the API caller.
hd	This element is optional. If you pass this element with 'true' value, then yc-360 script will trigger heap dump on the target process. If you pass 'false' value as the value, then yc-360 script will NOT trigger heap dump on the target process. This value will over-ride whatever the 'hd' argument value that is already configured in the yc-360 script.
tags	This element is optional. If you would like to tag an incident, then you pass this element. These tags will show up in the yCrash dashboard. You can pass multiple tags delimited by a comma. Example: jiraTicket-1232, release-2022-09, pre-prod

# Identifying Process

Suppose you are using 'Action API' or 'Remote Capture' feature, then you need to pass a token which can uniquely identify the process on which you want to capture the troubleshooting artifacts (i.e. thread dump, heap dump, GC log,...). You can pass one of the following token:

Process ID
Unique Arguments of the process
PROCESS_HIGH_CPU
PROCESS_HIGH_MEMORY
PROCESS_UNKNOWN

Let's review these options in this section.

1. Process ID

You can pass the process Id of the target process on which you want to capture the troubleshooting artifacts. (Not sure how to find process Id? Learn here (opens new window)).

2. Unique Arguments of the process

You can pass a unique token (or argument) with which the target process is launched. The yc-360 script will do 'ps -ef | grep <TOKEN>' on the device. If any matching process is found, then the yc-360 script will do root cause analysis on that particular process. Say, for example, your application is launched with the following arguments:

java -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:/tmp/my-gc.log -jar buggyApp.jar bug2

Since this process is launched with the unique string token 'buggyApp.jar', you can pass the 'buggyApp.jar' as the token. Based on this token yc-360 script will identify the process.

Example:

"actions": ["capture buggyApp.jar"]

Note: If the string token you are passing is not unique and multiple processes are matched, then the first matching process Id will be chosen to do root cause analysis.

3. PROCESS_HIGH_CPU

Say suppose you got a CPU spike alert from your monitoring tool. But monitoring tool didn't report the process Id. You can pass 'capture PROCESS_HIGH_CPU' as the value in the 'actions' element. i.e.

"actions": ["capture PROCESS_HIGH_CPU"]

When you pass this keyword, the yc-360 script will capture the artifacts from the device's maximum CPU consuming process and do the root cause analysis.

4. PROCESS_HIGH_MEMORY

Say suppose you got a memory alert from your monitoring tool. But monitoring tool didn't report the process Id. You can pass 'capture PROCESS_HIGH_MEMORY' as the value in the 'actions' element. i.e.

"actions": ["capture PROCESS_HIGH_MEMORY"]

When you pass this keyword, the yc-360 script will capture the artifacts from the device's maximum memory consuming process and do the root cause analysis.

5. PROCESS_UNKNOWN

Say suppose you got a alert from your monitoring tool. But don't know the reason for it i.e. you don't know whether alert was generated for CPU spike or memory spike or response time degradation. You can pass 'capture PROCESS_UNKNOWN' as the value in the 'actions' element. i.e.

"actions": ["capture PROCESS_UNKNOWN"]

When you pass this keyword, the yc-360 script will capture the artifacts from the device's maximum CPU consuming process and maximum memory consuming process and do the root cause analysis.

# Response Payload

When you submit above request payload, following response payload will be sent back to you:

{
   "Code":0,
   "Msg":"",
   "DashboardReportURLs":[
      "http://13.57.16.187:6010/yc-report.jsp?ou=Lunar&de=172.31.2.226&app=yc&ts=2021-04-29T15-28-08"
   ]
}

1
2
3
4
5
6
7

Here is the description of response payload elements:

Element	Description
Code	This element contains the API response status code. If the API is successfully executed, then '0' will be returned. If API failed to execute then '-1' will be returned.
Msg	When the API fails, reason for failure will be sent in this element. This element will be empty if API is executed successfully.
DashboardReportURLs	This element will be sent back only if 'waitFor: true' is passed in the request. This element contains the dashboard report URL, where you can find the root cause analysis report generated for the current API request.

# Action API for Kubernetes

In Kubernetes' world, Pod's IP addresses are private. They are not exposed outside. In such circumstances, it's going to be tricky to trigger an action API on the yc-360 script that is running on a particular pod. Typically Ingres type of load balancing solution exists in front of the kubernetes cluster. When the action API is triggered, load balancer will route the request to any one of the pods in the cluster and not to a specific yc-360 script running in the pod. To address this problem, we have introduced the 'yCrash-forward' HTTP Header element. This element will have the end-point of where the request should be sent to. Example:

ycrash-forward: http://192.34.89.01:8085/action

When the load balancer routes the request to one of the yc-360 script's running in the pods, the yc-360 script will inspect whether the 'ycrash-forward' element is present in the HTTP header. If it is present, it will forward the request to the end point specified in this element, otherwise the yc-360 script will process it.

← yc-360 Script Response How to run yc-360 Script as a Linux System Service (systemctl)? →