README.md

Lambda Endpoint

Requirements

• A postgresql server
• libpq installed

Config

/config/settings.yml contains the port and database settings, please refer to yesod's document.

/config/lambda-settings.yml contains the configuration specified for lambda project.

• root-password: since trace must be run in superuser mode, you should provide a root password here, this will be used in sudo command.

• bpf/stap-path: path to the executables.

• submit-chunk-size: http trace results submitting chuck size (in bytes).

• platform-url: url of the platform.

• secret: secret key to verify the identity.

• endpoint-uuid: uuid to identify endpoint.

Authorization

The communication between the endpoint and the server must be verified. The method is to add a Authorization header. The format is as the following:

[uuid][argon2 of password]

example:

4633d686-f75d-4d1f-8415-02ce37d9e5f8$argon2i$v=19$m=4096,t=3,p=1$lxQKK/JGRLqc01yCPpJvSw$FUjxqpeiwORBGcgzPSytgHf1LTdbMLbGOyCqg61BJoM

API

• /heartbeat GET: return a json with field status and time. status should be alive and time should be the utc time when replying the request.

• /traces GET: get all traces in the database. The format is as following

   {
   	"traceNo": 1, // database id
   	"info": {
   		"process": "/bin/bash", // the process to trace
   		"funtions": ["xmalloc", "xfree"], // the functions to trace
   		"environment": [], // additional environment variables
   		"value": [], // correspoinding value to environment variables
   		"options": [], // addtional options
   		"traceType": [] // BPF or STAP
   	}
   }
  

• /trace PUT: put a trace template to the database. The content type must be set as application/json. The body format is as the following:

   {
   	"process": "/bin/bash", // the process to trace
   	"funtions": ["xmalloc", "xfree"], // the functions to trace
   	"environment": [], // additional environment variables
   	"value": [], // correspoinding value to environment variables
   	"options": [], // addtional options
   	"traceType": [] // BPF or STAP
   }
  

• /trace/start POST: start the trace. The content type must be set as application/json. The body format is as the following:

   {
   	"traceT": "STAP", // trace type
   	"traceId": 1, // trace id (database)
   	"lasting": 3600, // the lasting time of trace (in seconds) 
   }
  

  The return form is also json:

   {
   	"thread": 54, // light weight haskell thread id
   	"filePath": "/tmp/4633d686-f75d-4d1f-8415-02ce37d9e5f8.trace" // used as the identifier of a trace
   }
  

  The trace info will be sent to the server via several HTTP PUT request. The url is "/submit"

  • At the beginning, a start request will be sent:

    {
        "trace": "/tmp/4633d686-f75d-4d1f-8415-02ce37d9e5f8.trace",
        "status": "start"
    }
    

  • Then, whenever the buffer limit is reached, a request contains chunked trace result will be sent.

    {
    	  "trace": "/tmp/4633d686-f75d-4d1f-8415-02ce37d9e5f8.trace",
        "no": <integer represents the chunk number (increasing)>,
        "field": <BASE64 of current chunk info>
    }
    

  • When finished, a finishing request will be sent:

    {
        "trace": "/tmp/4633d686-f75d-4d1f-8415-02ce37d9e5f8.trace",
        "stderr": <as the name>,
        "code": <exit code>,
        "status": "finished"
    }
    

• /trace/remove POST: remove a trace from the database. The content type must be set as application/json. The body format is as the following:

   {
   	"removeType": "STAP", // trace type
   	"removeId": 5 // trace id
   }
  

• /trace/running GET: get a running trace info. Example url: /trace/running?path=/tmp/4633d686-f75d-4d1f-8415-02ce37d9e5f8.trace. The return format is json:

   {
   	"process": "/bin/bash", // the process to trace
   	"funtions": ["xmalloc", "xfree"], // the functions to trace
   	"environment": [], // additional environment variables
   	"value": [], // correspoinding value to environment variables
   	"options": [], // addtional options
   	"traceType": [] // BPF or STAP
   }
  

• /traces/running/all GET: get all running traces. The return type is json list. Objects is same as /trace/running GET.

• /trace/kill POST: kill a running trace. Return a plaintext Killed. It will not check whether the given process exists or not, but simply ignores those non-exsiting process. The request format should be

   {
   	"killPath": "/tmp/4633d686-f75d-4d1f-8415-02ce37d9e5f8.trace"
   }