Audrey Reporting API

Audrey Reporting API

The Audrey Reporting API is provided to allow clients to access configuration status information from an Audrey Config Server for registered deployments.

Clients

Clients will use HTTPS to connect to the API endpoints. The API endpoints will return XML formatted data. Initially, the only envisioned client is Conductor.

API Endpoints

The Audrey Reporting API will start with two API HTTPS endpoints:

• /reports/deployment/$UUID
• /reports/instance/$UUID

Authentication & Authorization

Authentication will be handled by OAuth. Authorization is implied by successful authentication.

API Status Codes

Since the API will be implemented as an HTTP endpoint, so all the API status codes will map to HTTP status codes:

• 200: The API implementation successfully processed the request
• 404: The API implementation could not find the data associated with the given UUID (either deployment or instance)
• 50x: The API implementation failed to process the request and/or the request caused an error on the server

Deployment Reporting API

The Deployment Reporting API is used to retrieve a summary of a deployment’s configuration status. The API for deployments will present the following data:

• registered: conductor has posted configs for all instances in a deployment to the config server
  • in the first iteration of the implementation, the registered data will simply indicate when the first instance for a deployment registered
• status: indicates whether all the services in the deployment have been configured
  • success when all the service scripts of all the instances in the deployment have a exit status of 0
  • incomplete when some of the services on the instances in the deployment are not yet configured
  • error when at least one of the services on the instances has reported a non-zero exit status
  • Note: this data depends on the service dependency and independent service handling feature (#2941)

Additionally, for each instance in the deployment, the api will present the following data:

• uuid: the instance UUID
• assembly: the original assembly name for the instance
• status: the configuration status
  • success indicates that all of the service scripts for the instance reported an exit status of 0
  • incomplete indicates that at least one service script has not reported a status
  • error indicates that at least one service script reported a non-zero status

Deployment reporting XML format

  <deployment uuid="UUID" status="success/incomplete/error">
    <registered>Timestamp (date/time)</registered>
    <completed>Timestamp (date/time)</completed>
    <instances>
      <instance uuid="UUID" assembly="original_assembly_name" status="success/incomplete/error"/> 
      <instance uuid="UUID" assembly="original_assembly_name" status="success/incomplete/error"/>
    </instances>
  </deployment>

Instance Reporting API

The Instance Reporting API is used to retrieve the details of a particular instance’s configuration status. The API for instances will present the following data:

• registered and contacted: timestamp values indicating when either happened
  • registered: the instance configs were registered by conductor (via POST /configs)
  • contacted: the instance has contacted the config server
• status: indicates whether all the services in the instance have been configured
  • success when all of the service scripts on the instance have reported an exit status of 0
  • incomplete when some of the services on the instance have not been been marked successfully configured
  • error when at least one of the services on the instance reported a non-zero exit status
  • Note: this data depends on the service dependency and independent service handling feature (#2941)
• timestamp of last contact: the last time the instance contacted the config server

Additionally, for each service in the instance, the API for instances will present the following data:

• status: indicates whether the service has been successfully configured
  • success when the service script on an instance has reported an exit status of 0
  • incomplete when the service on an instance is not yet configured
  • error when the service reports a non-zero exit status
  • Note: this data depends on the service dependency and independent service handling feature (#2941)
• configuration timestamps: the start and end time of the service configuration
  • timestamp of configuration start: the time that the configuration started for a service
  • timestamp of configuration end: the time that the configuration ended for a service
  • Note: this data depends on the service dependency and independent service handling feature (#2941)
• unresolved service parameters: service input parameters that are waiting on other assemblies’ return values
• pending return parameters: instance return parameters that have not yet been received by the config server

Instance reporting XML format

  <instance uuid="UUID" assembly="original_assembly_name" status="success/incomplete/error">
    <registered>Timestamp (date/time)</registered>
    <first-contacted>Timestamp (date/time)</first-contacted>
    <last-contacted>Timestamp (date/time)</last-contacted>
    <completed>Timestamp (date/time)</completed>
    <services>
      <service name="NAME" status="success/incomplete/error">
        <configuration-started>Timestamp (date/time)</configuration-started>
        <configuration-ended>Timestamp (date/time)</configuration-ended>
        <completion-status>EXIT_CODE</completion-status>
        <unresolved-service-parameters>
          <service-parameter name="PARAM_NAME">
            <source-assembly uuid="SOURCE_ASSEMBLY_UUID" name="SOURCE_ASSEMBLY_NAME"/>
            <source-parameter name="SOURCE_RETURN_PARAMETER_NAME"/>
          </service-parameter>
        </unresolved-service-parameters>
      </service>
    </services>
    <pending-return-parameters>
      <return-parameter name="PARAM_NAME"/>
    </pending-return-parameters>
  </instance>