Event Reference

This reference describes the content of events published to clients streaming events from the Events System.

Common event fields

All event objects contain the following fields:

Field Description
resource FQN of the resource that generated the event.
event_source The source of the change that caused the event.
time Unix time when the event was generated.
type The event type. Currently, this is always "0".
payload The event payload. The payload contents depend on the resource type specified by resource .

Example event:

{
  "event_source": "",
  "payload": { ... },
  "resource": "package::/sandbox/tim.statler::myapp",
  "time": 1.4666271333442785E+18,
  "type": 0
}

Job and instance events

Event streams for subscriptions on the job:: realm contain the following types of events:

Job events

Job events are published in response to job creation and deletion, route changes, service binding changes, and other job updates.

The payload field of each job event may contain the following fields. Some fields are only present for certain job actions, as noted below:

Field Description
action Action that caused this event to be published. See Job event actions for a list of possible actions.
bound_services A map of service binding FQNs to FQNs of services newly bound to the job. Only present for job_binding_add event actions.
created_by Principal name of the user who created the job.
create_time Unix timestamp that indicates when the job was created.
job_uuid UUID of the job from which this event was published.
labels A map of user-defined label names to values placed on the job. Omitted if job has no defined labels.
network The FQN of the virtual network that the job joined or left. Only present for job_network_join and job_network_leave event actions.
num_instances The expected number of job instances at the time the event was generated.
update_endpoint API endpoint at which the Job can be updated.
update_time Unix timestamp that indicates when the job was last updated.
updated_by Principal name of the user who last updated the job.
user Principal name of the user who generated the event.
unbound_services A map of service binding FQNs to FQNs of newly unbound services. Only present for job_binding_remove event actions.
routes An array of the routes added, updated, or removed from the job. Only present for job_routes_add, job_routes_remove and job_routes_change event actions.
tags Set of tags applied to the job. Note that these are not job scheduling tags.

Job event actions

The following table lists the actions that generate a job event.

Action name Description
job_binding_add A new service binding was created on the job.
job_binding_remove An existing service binding was removed from the job.
job_create Job was created.
job_delete Job deleted.
job_error Job exited with non-zero exit code.
job_finish Job finished with a zero exit code.
job_instances_add The number of requested job instances was increased.
job_network_join The job joined a virtual network.
job_network_leave The job left a virtual network.
job_num_instances_change The number of job instances was increased or decreased.
job_routes_add A route was added to the job.
job_routes_change The routes on the job were changed.
job_routes_remove A route was removed from the job.
job_start Job was started.
job_update A job update occurred that was not one of the predefined types.

Example event for job_routes_add action:

{
  "event_source": "api_server@apcera.me",
  "payload": {
    "action": "job_routes_add",
    "create_time": 1.4666216476451658E+18,
    "created_by": "admin@apcera.me",
    "job_uuid": "14c03a0e-2dea-42f6-9991-aa88220fccea",
    "num_instances": 1,
    "routes": [
      "http://myapp.example.com"
    ],
    "tags": {
      "app": "myapp"
    },
    "update_time": 1.4666219488540247E+18,
    "updated_by": "admin@apcera.me",
    "user": "admin@apcera.me"
  },
  "resource": "job::/sandbox/admin::myapp",
  "time": 1.4666219488555164E+18,
  "type": 0
}

Example event for job_binding_add action:

{
  "event_source": "api_server@apcera.me",
  "payload": {
    "action": "job_binding_add",
    "bound_services": {
      "binding::/::53892db1-cc23-401c-94f5-b4940b49e550": "service::/apcera::http"
    },
    "create_time": 1.4666216476451658E+18,
    "created_by": "admin@apcera.me",
    "job_uuid": "14c03a0e-2dea-42f6-9991-aa88220fccea",
    "labels": {
      "foo": "bar"
    },
    "num_instances": 1,
    "tags": {
      "app": "myapp"
    },
    "update_time": 1.4666228591560084E+18,
    "updated_by": "admin@apcera.com",
    "user": "admin@apcera.com"
  },
  "resource": "job::/sandbox/admin::myapp",
  "time": 1.4666228604146824E+18,
  "type": 0
}

Example event for job_network_join action:

{
  "event_source": "api_server@apcera.me",
  "payload": {
    "action": "job_network_join",
    "create_time": 1.4666216476451658E+18,
    "created_by": "admin@apcera.me",
    "job_uuid": "14c03a0e-2dea-42f6-9991-aa88220fccea",
    "labels": {
      "foo": "bar"
    },
    "network": "network::/sandbox/admin::timnet[192.168.1.0/24]",
    "num_instances": 1,
    "tags": {
      "app": "myapp"
    },
    "update_time": 1.466624821510119E+18,
    "updated_by": "admin@apcera.com",
    "user": "admin@apcera.com"
  },
  "resource": "job::/sandbox/admin::myapp",
  "time": 1.4666248215229002E+18,
  "type": 0
}

Instance resource usage events

Resource usage events contain CPU, disk, memory, and network usage metrics for all job instances specified by the event subscription FQN and are published published automatically every 10 seconds. Resource usage event payloads do not contain an action field, and the top-level event_source is empty.

If the subscription FQN you specify is a namespace (like job::/dev) rather than a specific FQN (job::/dev::job1) instance resource usage events are generated for instances of all jobs in that namespace (that you have permission to read).

The payload object of each resource usage event contains the following fields:

Field name Description
cpu Amount of CPU time (in nanoseconds) being used by the instance.
cpu_total Total CPU usage reserved for the instance in milliseconds of CPU time per second of physical time. If no CPU reservation was specified then this property is 0.
disk_total Total disk space reserved for the instance.
disk_used Amount of disk space being used by the instance.
job_fqn FQN of the job that this instance was running.
job_uuid UUID of the job for which this event was published.
instance_uuid UUID of the instance for which this event was published.
memory_total Total memory reserved for the instance.
memory_used Amount of memory being used by the instance.
network_total Total network throughput allowed in bytes/sec. Applies to all network interfaces.
network_used A map of available network interfaces to network throughput used by each interface.
timestamp Unix timestamp for when for the metric was recorded.

Example instance metric event:

{
  "event_source": "",
  "payload": {
    "cpu": 2.5615E+6,
    "disk_total": 1073741824,
    "disk_used": 1544192,
    "instance_uuid": "165a343b-e40c-4e94-95dd-992d949873c2",
    "job_fqn": "job::/sandbox/admin::myapp",
    "job_uuid": "8de704ef-d81f-4fae-88da-73de20162420",
    "memory_total": 268435456,
    "memory_used": 5541888,
    "network_total": 5E+6,
    "network_used": {
      "veth-165a343b": {
        "RxBytes": 510,
        "TxBytes": 696
      }
    },
    "timestamp": 1466620067
  },
  "resource": "job::/sandbox/admin::myapp",
  "time": 1.4666200674659802E+18,
  "type": 0
}

Instance life-cycle events

Instance life-cycle events are generated in response to changes in a job instance's life-cycle. The following lists the actions that cause an instance life-cycle event to be generated:

Event name Description
instance_port_dial_failed Health probe on a port failed.
instance_process_failed Process failed.
instance_process_out_of_memory Process ran out of memory.
instance_remote_volume_mount_failed Failed to mount remote volume.
instance_service_binding_failed Service binding failed.
instance_state_transition_failed Failed to move instance from one state to another

The payload object of each instance life-cycle event contains the following fields:

Field Description
action Action that caused the event to be generated (see table above).
create_time Unix time at which this instance was created.
host Name of the host the instance is running on.
instance_exited Boolean that's set to true if the instance was started and any of the processes exited on its own naturally, rather than the platform shutting it down.
instance_exit_code The exit code of the main process of an instance. This should only be checked if instance_exited is set to true.
instance_failed Boolean that indicates if this instance has failed.
instance_state State of the instance at the time the event was published.
instance_uuid UUID of the instance for which this event was published.
job_fqn FQN of the job that this instance was running.
job_uuid UUID of the job for which this event was published.

Example instance life-cycle event generated by a instance_port_dial_failed action:

{
  "event_source": "",
  "payload": {
    "action": "instance_port_dial_failed",
    "create_time": 1.4666200266975078E+18,
    "host": "cosmic-bce01afc",
    "instance_exit_code": 0,
    "instance_exited": false,
    "instance_failed": false,
    "instance_state": "FIRST_RUNNING",
    "instance_uuid": "9735178d-8c9f-4c6c-9a26-526ad2e100ce",
    "job_fqn": "job::/sandbox/tim.statler::myapp",
    "job_uuid": "8de704ef-d81f-4fae-88da-73de20162420"
  },
  "resource": "job::/sandbox/tim.statler::myapp",
  "time": 1.4666200580214856E+18,
  "type": 0
}

Network events

Network events are published when a virtual network is created or deleted. The following actions cause a network event to be published:

Action name Description
network_create A network was created.
network_delete A network was deleted.

The payload object of each network event contains the following fields:

Field name Description
action Action that caused this event to be published (see table above).
create_time Unix timestamp that indicates when the network was created.
created_by Principal name of the user who created the network.
network_uuid UUID of the network from which this event originated.
update_time Unix timestamp that indicates when the network was last updated.
updated_by Principal name of the user who last updated the network.
user Principal name of the user who generated the event.
subnet Network's assigned subnet.

Example network_delete event:

{
  "event_source": "api_server@apcera.me",
  "payload": {
    "action": "network_delete",
    "create_time": 1.4665395837048737E+18,
    "created_by": "tim.statler@apcera.com",
    "network_uuid": "83af89fd-6e71-4674-8048-d7d16b5fa2bb",
    "subnet": "192.168.1.0/24",
    "update_time": 1.4666259039345516E+18,
    "user": "admin@apcera.me"
  },
  "resource": "network::/sandbox/tim.statler::timnet",
  "time": 1.4666259116627046E+18,
  "type": 0
}

Package and staging events

Package events are published when a package is created, updated, or deleted. They also contain events related to staging of packages.

The following lists the actions that cause a package event to be published.

Action name Description
package_create A package was created.
package_delete A package was deleted.
package_update A package was updated.
staging_aborted Staging was aborted for the package resource.
staging_complete Staging was completed for the package resource.
staging_stager_job_failed A stager job in the staging pipeline failed.
staging_started Staging started for the package resource.

The payload object of each package event contains the following fields:

Field Description
action Action that caused this event to be published (see table above).
create_time Unix timestamp that indicates when the package was created.
created_by Principal name of the user who created the package.
num_stagers Number of stagers in the staging pipeline specified by pipeline.
package_uuid UUID of the package that generated this event.
pipeline FQN of the staging pipeline.
stager FQN of the current stager.
update_time Unix timestamp that indicates when the package was last updated.
updated_by Principal name of the user who last updated the package.
user Principal name of the user who generated the event.
tags Set of tags present on the package that generated this event.

Example package_update event:

{
  "event_source": "staging_coordinator@apcera.me",
  "payload": {
    "action": "package_update",
    "create_time": 1.4666271306074486E+18,
    "created_by": "admin@apcera.me",
    "package_uuid": "44b7f294-e67f-46d6-8c4c-bad556850b9a",
    "user": "staging_coordinator@apcera.me"
  },
  "resource": "package::/sandbox/tim.statler::myapp",
  "time": 1.4666271351052396E+18,
  "type": 0
}

Example staging_complete event:

{
  "event_source": "",
  "payload": {
    "action": "staging_complete",
    "num_stagers": 1,
    "pipeline": "stagpipe::/apcera::static-site",
    "stager": "job::/sandbox/tim.statler::static-site/stager/myapp/6e659477/6901da15",
    "user": ""
  },
  "resource": "package::/sandbox/tim.statler::myapp",
  "time": 1.4666285240229076E+18,
  "type": 0
}

Provider events

Provider events are published when a provider is created or deleted. The actions cause a provider event to be published.

Action name Description
provider_create A provider was created.
provider_delete A provider was deleted.

The payload object of each provider event contains the following fields:

Field Description
action Action that caused this event to be published (see table above).
backing_job_fqn FQN of the job that backs this provider, if the provider is backed by a job. This field is omitted for providers that are backed by an external service.
backing_job_port If the provider has an internal backing job, specifies the port number exposed on in the backing job. Omitted for providers without an internal backing job.
create_time Unix timestamp that indicates when the provider was created.
created_by Principal name of the user who created the provider.
provider_uuid UUID of the provider that generated this event.
service_type The provider's service type (e.g., "postgres").
status The provider's status.
update_time Unix timestamp that indicates when the provider was last updated.
user Principal name of the user who modified the provider to cause the event to be generated.

Example provider_create event:

{
  "event_source": "admin@apcera.me",
  "payload": {
    "action": "provider_create",
    "backing_job_fqn": "job::/sandbox/tim.statler::docker-mysql-server",
    "backing_job_port": "3306",
    "create_time": 1.4666280870605926E+18,
    "created_by": "admin@apcera.me",
    "provider_uuid": "62f8a46d-41d4-4afd-96be-cf58b200eb57",
    "service_type": "mysql",
    "status": "",
    "update_time": 1.4666280870605926E+18,
    "user": "admin@apcera.me"
  },
  "resource": "provider::/sandbox/tim.statler::mysql-docker-provider",
  "time": 1.4666280870638241E+18,
  "type": 0
}

Service events

Service events are published when a service is created or deleted.

The following actions cause a service event to be published.

Action name Description
service_create A service was created.
service_delete A service was deleted.

The payload object of each service event contains the following fields:

Field Description
action Action that caused this event to be published (see table above).
create_time Unix timestamp in nanoseconds that indicates when the package was created.
created_by Principal name of the user who created the package.
service_uuid UUID of the service that generated this event.
service_type The service's type (e.g., 'postgres') corresponding to the service gateway used to manage the service.
status The service's status.
update_time Unix timestamp in nanoseconds that indicates when the package was last updated.
user Principal name of the user who modified the service to cause the event to be generated.

Example service_create event:

{
  "event_source": "tim.statler@apcera.com",
  "payload": {
    "action": "service_create",
    "create_time": 1.4666294390230904E+18,
    "created_by": "tim.statler@apcera.com",
    "service_type": "mongodb",
    "service_uuid": "af78f15f-986c-4c90-9cc8-d7b6fb4c80d8",
    "status": "",
    "update_time": 1.4666294390230904E+18,
    "user": "tim.statler@apcera.com"
  },
  "resource": "service::/sandbox/tim.statler::myservice",
  "time": 1.466629439026227E+18,
  "type": 0
}