8.8.4.0 | Services | Phone Home Service

The Phone Home service (a.k.a, Telemetry Service, Usage Statistics Service) is a service in Repose which will send usage data to a collection service. Usage data consists of the filters in use, the services in use, contact information, and other information relating to a specific instance of Repose. When enabled, this data is sent to a collection service owned and managed by the Repose team. This data is used to improve Repose as a product by providing insight into common usage patterns and metrics.

Configuration

Default Configuration: system-model.cfg.xml
Released: v7.1.5.1
Schema

Service Configuration

The Phone Home service is activated by adding a phone-home element to the system model configuration file and setting the enabled attribute to true. This element is included in the default Repose installation, but is disabled. Explicit action must be taken for the Phone Home service to be used.

system-model.cfg.xml

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
    <repose-cluster id="repose">
        ...
    </repose-cluster>

    <!-- Please set the enabled attribute to true to send us usage updates and help us improve Repose! -->
    <phone-home enabled="false" (1)
                origin-service-id="your-service" (2)
                contact-email="your@service.com"/> (3)
</system-model>

1	The `phone-home` element’s `enabled` attribute must be set to `true` to activate this feature.
2	The name of the Service/API that this instance of Repose is in front of.
3	The contact email address for the origin service.

Message Logger Configuration

When the Phone Home service is disabled, or when it cannot successfully send an update message to the configured data collection service, the content of the update that would have been sent will be logged to a logger named phone-home-message. A user may choose for this logger to append to a separate file, or to simply append to the regular log file. If the output of this logger is captured somewhere, a user may manually transmit the message generated by the Phone Home service wherever the user desires. Note that using this logger provides an easy way to inspect exactly what the Phone Home service is sending over the wire to the data collection service. An example logging configuration where Phone Home messages are logged to a file is shown below:

log4j2.cfg.xml

<Configuration>
    <Appenders>
        <Console name="STDOUT">
            <PatternLayout pattern="%d %-4r [%t] %-5p %c - %m%n"/>
        </Console>
        <!-- This is the appender to be used by the Phone Home service.
             It will log to the phone-home.log file, and will only keep the most recent message in the log. -->
        <File name="PhoneHomeMessages" fileName="/var/log/repose/phone-home.log" append="false"> (1)
            <PatternLayout>
                <Pattern>%m</Pattern>
            </PatternLayout>
        </File>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="STDOUT"/>
        </Root>
        <!-- This is the Phone Home service logger.
             It will only log to the PhoneHomeMessages appender, and not to STDOUT. -->
        <Logger name="phone-home-message" level="info" additivity="false"> (2)
            <AppenderRef ref="PhoneHomeMessages"/>
        </Logger>
    </Loggers>
</Configuration>

1	Configure a separate file appender.
2	Configure the logger to use the appender.