Reports reference

This page describes the concept behind the reporting in Rudder, and specifically how to write the Techniques to get proper reporting in Rudder

Concepts

Each Technique, when converted into a Directive and applied to a Node, must generate reports for Rudder to get proper compliance reports. This reports must contains specific information :

  • The Report type, that can be logs for information purpose or result to express a compliance

  • The Rule Id (autogenerated)

  • The Directive Id (autogenerated)

  • The Version Id (revision of the Rule) (autogenerated)

  • The name of the component the report is related to

  • The value of the key variable in the component (or None if not available)

  • The Execution Timestamp, to know in which execution of the agent the policy has been generated

These reports are sent via Syslog to the Rudder Root Server, parsed and put in a database, that is queried to generate the reporting

Report format

A report has the following format :

@@Technique@@Type@@RuleId@@DirectiveId@@VersionId@@Component@@Key@@ExecutionTimeStamp##NodeId@#HumanReadableMessage
  • Technique : Human readable Technique name

  • Type : type of report (see bellow)

  • RuleId : The Id of the Configuration Rule, autogenerated

  • DirectiveId : The Id of the Directive, autogenerated

  • VersionId : the revision of the ConfigurationRule, autogenerated

  • Component : the name of the component this Directive is related to (if no component are defined in the metadata.xml, then the Technique name is used)

  • Key : the value of the reference variable. If there is no reference variable, then the value None should be used

  • ExecutionTimeStamp : the timestamp of the current agent execution

  • NodeId : the id of the node

  • HumanReadableMessage : a message than a Human can understand

Valid report types

Table 1. Report Types
Name Type Mode Max number Details

log_trace

log

any

infinity

Should be used for advanced debuging purpose only.

log_debug

log

any

infinity

Should be used for debug purpose only.

log_info

log

any

infinity

Use for standard logging purposes.

log_warn

log

any

infinity

Used for logging only for the moment. Should be used when something unexpected happens.

log_repaired

log

enforce

infinity

Used for logging purposes, to list all that is repaired by the policies.

result_na

result

enforce

one per component/key

Defines the status of the Component to Not Applicable (if there are no result_success, result_repaired, result_error). Should be used only when the component is not applicable because it does not match the target context.

result_success

result

enforce

one per component/key

Defines the status of the Component to Success (if there are no result_repaired or result_error). Should be used only when everything is already in the correct state in this component for this key.

result_repaired

result

enforce

one per component/key

Defines the status of the Component to Repaired (if there are no result_error). Should be used only when something was not in the correct state, but could be corrected.

result_error

result

enforce

infinity per component/key

Defines the status of the Component to Error. Should be used when something was not in the correct state, and could not be corrected.

audit_na

result

audit

one per component/key

Defines the status of an Component to Not Applicable (if there are no result_success, result_repaired, result_error). Should be used only when the component is not applicable because it does not match the target context.

audit_compliant nent was not applicable to the node.

result

audit

one per component/key

Defines the status of the Component to Compliant (if there are no audit_noncompliant or audit_error). Should be used only when everything is already in the correct state in this component for this key.

audit_noncompliant

result

audit

one per component/key

Defines the status of the Component to Non Compliant (if there are no audit_error). Should be used only when something was not in the correct state.

audit_error

result

audit

infinity per component/key

Defines the status of the Component to Error. Should be used when the audit could not be done or was interrupted.

Variables used to generate the reports

Some facilities have been created to help putting the right values at the right place

  • &TRACKINGKEY&: this is an auto generated variable, put in the technique file, that Rudder will replace when writing the policies by

<pre>RuleId@@DirectiveId@@VersionId
  • $(g.execRun): this is replaced at runtime by the agent to the current execution time

  • $(g.uuid): this is replaced at runtime by the agent to the Node Id