mirror of
https://github.com/fnproject/fn.git
synced 2022-10-28 21:29:17 +03:00
cbe0d5e9ac
* add user syslog writers to app users may specify a syslog url[s] on apps now and all functions under that app will spew their logs out to it. the docs have more information around details there, please review those (swagger and operating/logging.md), tried to implement to spec in some parts and improve others, open to feedback on format though, lots of liberty there. design decision wise, I am looking to the future and ignoring cold containers. the overhead of the connections there will not be worth it, so this feature only works for hot functions, since we're killing cold anyway (even if a user can just straight up exit a hot container). syslog connections will be opened against a container when it starts up, and then the call id that is logged gets swapped out for each call that goes through the container, this cuts down on the cost of opening/closing connections significantly. there are buffers to accumulate logs until we get a `\n` to actually write a syslog line, and a buffer to save some bytes when we're writing the syslog formatting as well. underneath writers re-use the line writer in certain scenarios (swapper). we could likely improve the ease of setting this up, but opening the syslog conns against a container seems worth it, and is a different path than the other func loggers that we create when we make a call object. the Close() stuff is a little tricky, not sure how to make it easier and have the ^ benefits, open to idears. this does add another vector of 'limits' to consider for more strict service operators. one being how many syslog urls can a user add to an app (infinite, atm) and the other being on the order of number of containers per host we could run out of connections in certain scenarios. there may be some utility in having multiple syslog sinks to send to, it could help with debugging at times to send to another destination or if a user is a client w/ someone and both want the function logs, e.g. (have used this for that in the past, specifically). this also doesn't work behind a proxy, which is something i'm open to fixing, but afaict will require a 3rd party dependency (we can pretty much steal what docker does). this is mostly of utility for those of us that work behind a proxy all the time, not really for end users. there are some unit tests. integration tests for this don't sound very fun to maintain. I did test against papertrail with each protocol and it works (and even times out if you're behind a proxy!). closes #337 * add trace to syslog dial
770 lines
21 KiB
YAML
770 lines
21 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: fn
|
|
description: The open source serverless platform.
|
|
version: "0.2.4"
|
|
# the domain of the service
|
|
host: "127.0.0.1:8080"
|
|
# array of all schemes that your API supports
|
|
schemes:
|
|
- https
|
|
- http
|
|
# will be prefixed to all paths
|
|
basePath: /v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
paths:
|
|
/apps:
|
|
get:
|
|
summary: "Get all app names."
|
|
description: "Get a list of all the apps in the system, returned in alphabetical order."
|
|
tags:
|
|
- Apps
|
|
parameters:
|
|
- name: cursor
|
|
description: Cursor from previous response.next_cursor to begin results after, if any.
|
|
required: false
|
|
type: string
|
|
in: query
|
|
- name: per_page
|
|
description: Number of results to return, defaults to 30. Max of 100.
|
|
required: false
|
|
type: integer
|
|
in: query
|
|
responses:
|
|
200:
|
|
description: List of apps.
|
|
schema:
|
|
$ref: '#/definitions/AppsWrapper'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
post:
|
|
summary: "Post new app"
|
|
description: "Insert a new app"
|
|
tags:
|
|
- Apps
|
|
parameters:
|
|
- name: body
|
|
in: body
|
|
description: App to post.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/AppWrapper'
|
|
responses:
|
|
200:
|
|
description: App details and stats.
|
|
schema:
|
|
$ref: '#/definitions/AppWrapper'
|
|
400:
|
|
description: Parameters are missing or invalid.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
409:
|
|
description: App already exists.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
|
|
/apps/{app}:
|
|
delete:
|
|
summary: "Delete an app."
|
|
description: "Delete an app."
|
|
tags:
|
|
- Apps
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: Name of the app.
|
|
required: true
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Apps successfully deleted.
|
|
404:
|
|
description: App does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
get:
|
|
summary: "Get information for a app."
|
|
description: "This gives more details about a app, such as statistics."
|
|
tags:
|
|
- Apps
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: name of the app.
|
|
required: true
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: App details and stats.
|
|
schema:
|
|
$ref: '#/definitions/AppWrapper'
|
|
404:
|
|
description: App does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
patch:
|
|
summary: "Updates an app."
|
|
description: "You can set app level settings here. "
|
|
tags:
|
|
- Apps
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: name of the app.
|
|
required: true
|
|
type: string
|
|
- name: body
|
|
in: body
|
|
description: App to post.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/AppWrapper'
|
|
responses:
|
|
200:
|
|
description: App details and stats.
|
|
schema:
|
|
$ref: '#/definitions/AppWrapper'
|
|
400:
|
|
description: Parameters are missing or invalid.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
404:
|
|
description: App does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/apps/{app}/routes:
|
|
post:
|
|
summary: Create new Route
|
|
description: Create a new route in an app, if app doesn't exists, it creates the app. Post does not skip validation of zero values.
|
|
tags:
|
|
- Routes
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: name of the app.
|
|
required: true
|
|
type: string
|
|
- name: body
|
|
in: body
|
|
description: One route to post.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
responses:
|
|
200:
|
|
description: Route created
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
400:
|
|
description: Invalid route due to parameters being missing or invalid.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
409:
|
|
description: Route already exists.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
get:
|
|
summary: Get route list by app name.
|
|
description: This will list routes for a particular app, returned in alphabetical order.
|
|
tags:
|
|
- Routes
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: Name of app for this set of routes.
|
|
required: true
|
|
type: string
|
|
- name: image
|
|
description: Route image to match, exact.
|
|
required: false
|
|
type: string
|
|
in: query
|
|
- name: cursor
|
|
description: Cursor from previous response.next_cursor to begin results after, if any.
|
|
required: false
|
|
type: string
|
|
in: query
|
|
- name: per_page
|
|
description: Number of results to return, defaults to 30. Max of 100.
|
|
required: false
|
|
type: integer
|
|
in: query
|
|
responses:
|
|
200:
|
|
description: Route information
|
|
schema:
|
|
$ref: '#/definitions/RoutesWrapper'
|
|
404:
|
|
description: App does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/apps/{app}/routes/{route}:
|
|
put:
|
|
summary: Create a Route if it does not exist. Update if it does. Will also create app if it does not exist. Put does not skip validation of zero values
|
|
description: Update or Create a route
|
|
tags:
|
|
- Routes
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: name of the app.
|
|
required: true
|
|
type: string
|
|
- name: route
|
|
in: path
|
|
description: route path.
|
|
required: true
|
|
type: string
|
|
- name: body
|
|
in: body
|
|
description: One route to post.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
responses:
|
|
200:
|
|
description: Route created or updated
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
400:
|
|
description: Invalid route due to parameters being missing or invalid.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
patch:
|
|
summary: Update a Route, Fails if the route or app does not exist. Accepts partial updates / skips validation of zero values.
|
|
description: Update a route
|
|
tags:
|
|
- Routes
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: name of the app.
|
|
required: true
|
|
type: string
|
|
- name: route
|
|
in: path
|
|
description: route path.
|
|
required: true
|
|
type: string
|
|
- name: body
|
|
in: body
|
|
description: One route to post.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
responses:
|
|
200:
|
|
description: Route updated
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
400:
|
|
description: Invalid route due to parameters being missing or invalid.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
404:
|
|
description: App / Route does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
get:
|
|
summary: Gets route by name
|
|
description: Gets a route by name.
|
|
tags:
|
|
- Routes
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: Name of app for this set of routes.
|
|
required: true
|
|
type: string
|
|
- name: route
|
|
in: path
|
|
description: Route name
|
|
required: true
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Route information
|
|
schema:
|
|
$ref: '#/definitions/RouteWrapper'
|
|
404:
|
|
description: Route does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
delete:
|
|
summary: Deletes the route
|
|
tags:
|
|
- Routes
|
|
description: Deletes the route.
|
|
parameters:
|
|
- name: app
|
|
in: path
|
|
description: Name of app for this set of routes.
|
|
required: true
|
|
type: string
|
|
- name: route
|
|
in: path
|
|
description: Route name
|
|
required: true
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Route successfully deleted.
|
|
404:
|
|
description: Route does not exist.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
default:
|
|
description: Unexpected error
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/apps/{app}/calls/{call}/log:
|
|
get:
|
|
summary: Get call logs
|
|
description: Get call logs
|
|
tags:
|
|
- Call
|
|
- Log
|
|
parameters:
|
|
- name: app
|
|
description: App Name
|
|
required: true
|
|
type: string
|
|
in: path
|
|
- name: call
|
|
description: Call ID.
|
|
required: true
|
|
type: string
|
|
in: path
|
|
responses:
|
|
200:
|
|
description: Log found
|
|
schema:
|
|
$ref: '#/definitions/LogWrapper'
|
|
404:
|
|
description: Log not found.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/apps/{app}/calls/{call}:
|
|
get:
|
|
summary: Get call information
|
|
description: Get call information
|
|
tags:
|
|
- Call
|
|
parameters:
|
|
- name: app
|
|
description: app name
|
|
required: true
|
|
type: string
|
|
in: path
|
|
- name: call
|
|
description: Call ID.
|
|
required: true
|
|
type: string
|
|
in: path
|
|
responses:
|
|
200:
|
|
description: Call found
|
|
schema:
|
|
$ref: '#/definitions/CallWrapper'
|
|
404:
|
|
description: Call not found.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/apps/{app}/calls:
|
|
get:
|
|
summary: Get app-bound calls.
|
|
description: Get app-bound calls can filter to route-bound calls, results returned in created_at, descending order (newest first).
|
|
tags:
|
|
- Call
|
|
parameters:
|
|
- name: app
|
|
description: App name.
|
|
required: true
|
|
type: string
|
|
in: path
|
|
- name: path
|
|
description: Route path to match, exact.
|
|
required: false
|
|
type: string
|
|
in: query
|
|
- name: cursor
|
|
description: Cursor from previous response.next_cursor to begin results after, if any.
|
|
required: false
|
|
type: string
|
|
in: query
|
|
- name: per_page
|
|
description: Number of results to return, defaults to 30. Max of 100.
|
|
required: false
|
|
type: integer
|
|
in: query
|
|
- name: from_time
|
|
description: Unix timestamp in seconds, of call.created_at to begin the results at, default 0.
|
|
required: false
|
|
type: integer
|
|
in: query
|
|
- name: to_time
|
|
description: Unix timestamp in seconds, of call.created_at to end the results at, defaults to latest.
|
|
required: false
|
|
type: integer
|
|
in: query
|
|
responses:
|
|
200:
|
|
description: Calls found
|
|
schema:
|
|
$ref: '#/definitions/CallsWrapper'
|
|
404:
|
|
description: Calls not found.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
definitions:
|
|
Route:
|
|
type: object
|
|
properties:
|
|
app_id:
|
|
type: string
|
|
description: App ID
|
|
path:
|
|
type: string
|
|
description: URL path that will be matched to this route
|
|
readOnly: true
|
|
image:
|
|
description: Name of Docker image to use in this route. You should include the image tag, which should be a version number, to be more accurate. Can be overridden on a per route basis with route.image.
|
|
type: string
|
|
headers:
|
|
type: object
|
|
description: Map of http headers that will be sent with the response
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: string
|
|
memory:
|
|
type: integer
|
|
format: uint64
|
|
description: Max usable memory for this route (MiB).
|
|
cpus:
|
|
type: string
|
|
description: Max usable CPU cores for this route. Value in MilliCPUs (eg. 500m) or as floating-point (eg. 0.5)
|
|
type:
|
|
enum:
|
|
- sync
|
|
- async
|
|
description: Route type
|
|
type: string
|
|
format:
|
|
enum:
|
|
- default
|
|
- http
|
|
- json
|
|
description: Payload format sent into function.
|
|
type: string
|
|
config:
|
|
type: object
|
|
description: Route configuration - overrides application configuration
|
|
additionalProperties:
|
|
type: string
|
|
timeout:
|
|
type: integer
|
|
default: 30
|
|
format: int32
|
|
description: Timeout for executions of this route. Value in Seconds
|
|
idle_timeout:
|
|
type: integer
|
|
default: 30
|
|
format: int32
|
|
description: Hot functions idle timeout before termination. Value in Seconds
|
|
annotations:
|
|
type: object
|
|
description: Route annotations - this is a map of annotations attached to this route, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes
|
|
additionalProperties:
|
|
type: object
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Time when route was created. Always in UTC.
|
|
readOnly: true
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Most recent time that route was updated. Always in UTC.
|
|
readOnly: true
|
|
|
|
App:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: App ID
|
|
readOnly: true
|
|
name:
|
|
type: string
|
|
description: "Name of this app. Must be different than the image name. Can ony contain alphanumeric, -, and _."
|
|
readOnly: true
|
|
config:
|
|
type: object
|
|
description: Application function configuration, applied to all routes.
|
|
additionalProperties:
|
|
type: string
|
|
annotations:
|
|
type: object
|
|
description: Application annotations - this is a map of annotations attached to this app, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes
|
|
additionalProperties:
|
|
type: object
|
|
syslog_url:
|
|
type: string
|
|
description: A comma separated list of syslog urls to send all function logs to. supports tls, udp or tcp. e.g. tls://logs.papertrailapp.com:1
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Time when app was created. Always in UTC.
|
|
readOnly: true
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Most recent time that app was updated. Always in UTC.
|
|
readOnly: true
|
|
|
|
RoutesWrapper:
|
|
type: object
|
|
required:
|
|
- routes
|
|
properties:
|
|
next_cursor:
|
|
type: string
|
|
description: cursor to send with subsequent request to receive the next page, if non-empty
|
|
readOnly: true
|
|
routes:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Route'
|
|
error:
|
|
$ref: '#/definitions/ErrorBody'
|
|
|
|
RouteWrapper:
|
|
type: object
|
|
required:
|
|
- route
|
|
properties:
|
|
message:
|
|
type: string
|
|
error:
|
|
$ref: '#/definitions/ErrorBody'
|
|
route:
|
|
$ref: '#/definitions/Route'
|
|
|
|
AppsWrapper:
|
|
type: object
|
|
required:
|
|
- apps
|
|
properties:
|
|
next_cursor:
|
|
type: string
|
|
description: cursor to send with subsequent request to receive the next page, if non-empty
|
|
readOnly: true
|
|
apps:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/App'
|
|
error:
|
|
$ref: '#/definitions/ErrorBody'
|
|
|
|
AppWrapper:
|
|
type: object
|
|
required:
|
|
- app
|
|
properties:
|
|
app:
|
|
$ref: '#/definitions/App'
|
|
error:
|
|
$ref: '#/definitions/ErrorBody'
|
|
|
|
CallsWrapper:
|
|
type: object
|
|
required:
|
|
- calls
|
|
properties:
|
|
next_cursor:
|
|
type: string
|
|
description: cursor to send with subsequent request to receive the next page, if non-empty
|
|
readOnly: true
|
|
calls:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Call'
|
|
error:
|
|
$ref: '#/definitions/ErrorBody'
|
|
|
|
CallWrapper:
|
|
type: object
|
|
required:
|
|
- call
|
|
properties:
|
|
call:
|
|
$ref: '#/definitions/Call'
|
|
description: "Call object."
|
|
|
|
LogWrapper:
|
|
type: object
|
|
required:
|
|
- log
|
|
properties:
|
|
log:
|
|
$ref: '#/definitions/Log'
|
|
description: "Call log entry."
|
|
|
|
Log:
|
|
type: object
|
|
properties:
|
|
call_id:
|
|
type: string
|
|
description: Call UUID ID
|
|
log:
|
|
type: string # maybe bytes, long logs wouldn't fit into string type
|
|
|
|
Call:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Call UUID ID.
|
|
readOnly: true
|
|
status:
|
|
type: string
|
|
description: Call execution status.
|
|
readOnly: true
|
|
error:
|
|
type: string
|
|
description: Call execution error, if status is 'error'.
|
|
readOnly: true
|
|
app_id:
|
|
type: string
|
|
description: App ID that is assigned to a route that is being executed.
|
|
readOnly: true
|
|
path:
|
|
type: string
|
|
description: App route that is being executed.
|
|
readOnly: true
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Time when call was submitted. Always in UTC.
|
|
readOnly: true
|
|
started_at:
|
|
type: string
|
|
format: date-time
|
|
description: Time when call started execution. Always in UTC.
|
|
readOnly: true
|
|
completed_at:
|
|
type: string
|
|
format: date-time
|
|
description: Time when call completed, whether it was successul or failed. Always in UTC.
|
|
readOnly: true
|
|
stats:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Stat'
|
|
description: A histogram of stats for a call, each is a snapshot of a calls state at the timestamp.
|
|
readOnly: true
|
|
|
|
Stat:
|
|
type: object
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
metrics:
|
|
type: object
|
|
properties:
|
|
net_rx:
|
|
type: integer
|
|
format: int64
|
|
net_tx:
|
|
type: integer
|
|
format: int64
|
|
mem_limit:
|
|
type: integer
|
|
format: int64
|
|
mem_usage:
|
|
type: integer
|
|
format: int64
|
|
disk_read:
|
|
type: integer
|
|
format: int64
|
|
disk_write:
|
|
type: integer
|
|
format: int64
|
|
cpu_user:
|
|
type: integer
|
|
format: int64
|
|
cpu_total:
|
|
type: integer
|
|
format: int64
|
|
cpu_kernel:
|
|
type: integer
|
|
format: int64
|
|
|
|
ErrorBody:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
readOnly: true
|
|
fields:
|
|
type: string
|
|
readOnly: true
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
$ref: '#/definitions/ErrorBody'
|