Stream Logs

This page describes usage specific to a9s LogMe2. It builds upon the information provided in Getting Started - Accessing a Service Instance.

Stream Application Logs to LogMe2

To use a9s LogMe2 with an application, create a Service Instance and bind the Service Instance to your application. For more information on managing Service Instances, see Managing Service Instances with the cf CLI.

note

When using a9s LogMe2, you can use the encrypted TCP endpoint from Fluentd to receive logs from an application running in Cloud Foundry. You can find this endpoint in your service key/binding under the syslog_drain_url that starts with syslog-tls://. See Binding/Service Key Options for more information.

Supported Protocols and Limitations

a9s LogMe2 supports the use of the Syslog Protocol (RFC 5424 and by extension RFC 3164) under the following standards:

• Transport Layer Security (TLS) Transport Mapping for Syslog RCF 5425
• Transmission of Syslog Messages over UDP RCF 5426
• Transmission of Syslog Messages over TCP RCF 6587

This means that your Syslog messages must reflect the requirements set by these standards such as, but not limited to:

• The timestamp of your Syslog messages must follow the format mentioned in section 6.2.3 of RFC 5424 (which is derived from RFC 3339).
• Your log source must be able to use nil as a timestamp when unable to obtain the system's time.

Furthermore, depending on whether your Syslog messages are being sent over UDP or TCP, they should take on a specific format.

For UDP the format takes on the shape of: <priority>version date hostname app_name proccess_id message_id structured_data message

Which would look like this:

<34>1 2023-12-12T14:37:35.569848Z <your_host> <your_app> 1234 ID98 [...] This is an app log message.

For TCP the format takes on the shape of: size <priority>version date hostname app_name proccess_id message_id structured_data message

Which would look like this:

196 <34>1 2023-12-13T14:37:35Z myhostname myapp - - - This is a sample syslog message23344

Timestamps

As you can see, the timestamp in the examples differ from one another. this is due to the fact that both are accepted by the Syslog protocol.

Stream a9s Service Logs to LogMe2

To use a LogMe2 Service Instance to monitor another Service Instance, follow the first two steps of Stream application logs to LogMe2 to create an a9s LogMe2 Service Instance.

note

In order for a9s LogMe2 to receive logs from another a9s Service Instance, you need to enable the Fluentd's UDP endpoint.

Create a Service Key

As described in Accessing a Service Instance - Create a Service Key a service key can be created for the a9s LogMe2 Service Instance by running:

cf create-service-key my-logme2-service SERVICE-KEY-NAME`

Example:

cf create-service-key my-logme2-service key1
cf service-key my-logme2-service key1

Output

{
  "cacrt": "-----BEGIN CERTIFICATE-----\nMIIDGzszfasde....8tn9ebYK0k2Qt\n-----END CERTIFICATE-----\n",
  "host": "https://d765411-os.service.dc1.dsf2.a9ssvc:9200",
  "password": "a9scbe8462ee571f12d95b3a950e1bf8b2445a59983",
  "syslog_drain_url": "syslog-tls://d765411-fluentd.service.dc1.dsf2.a9ssvc:6514",
  "username": "a9s94bd153ddf5978f1eae7c88b57a27721430600d2"
}

The following option can be used when creating a service key/binding:

Custom Parameter Name	Description	Possible Values
syslog-use-udp	Causes the protocol in the syslog_drain_url to be syslog:// instead of syslog-tls:// and removes the cacrt field.	yes / no

Example:

cf create-service-key my-logme2-service key2 -c '{"syslog-use-udp": "yes"}'
cf service-key my-logme2-service key2

Output

{
 "host": "https://d765411-os.service.dc1.dsf2.a9ssvc:9200",
 "password": "a9s905525a655930b2bdeb890023c478079734a6409",
 "syslog_drain_url": "syslog://d765411-fluentd.service.dc1.dsf2.a9ssvc:514",
 "username": "a9s19db1255257d8fb3ec3027444bf1d163dca21586"
}

Update Your Service

The cf update-service command used with the -c flag can let you stream your syslog to a third-party service. In this case, the command expects a JSON string containing the syslog key. For this, you need to give the URL given by the cf service-key command as a value for the syslog key.

cf update-service service-instance-to-monitor \
-c '{"syslog": ["d37f7da-fluentd.service.dc1.consul:514"]}'

See Your Logs

Regardless of the origin of the streamed logs, be it an application or a Service Instance, the process to see them on the OpenSearch Dashboard is as follows:

1. Before you can see your application logs, you need credentials. Credentials can be retrieved by first creating a Service Key with cf create-service-key my-logme2-service key1 and then displaying them:

   cf service-key my-logme2-service key1
   Output

   Getting key k1 for service instance rg-real as cf-admin-dataservices...
   
   {
     "cacrt": "-----BEGIN CERTIFICATE-----\nMIIDGzszfasde....8tn9ebYK0k2Qt\n-----END CERTIFICATE-----\n",
     "host": "https://d765411-os.service.dc1.dsf2.a9ssvc:9200",
     "password": "a9scbe8462ee571f12d95b3a950e1bf8b2445a59983",
     "syslog_drain_url": "syslog-tls://d765411-fluentd.service.dc1.dsf2.a9ssvc:6514",
     "username": "a9s94bd153ddf5978f1eae7c88b57a27721430600d2"
   }

tip

To learn more about the options available to you when creating a binding/service key, see Binding/Service Key Options.

You need the username and password field values for authentication.

2. Grab the Service Instance's dashboard URL with cf service my-logme2-service:

   Output

   (...)
   name:             my-logme2-service
   service:          a9s-logme2
   tags:
   plan:             logme2-single-small
   description:      This is the a9s LogMe2 service.
   documentation:    https://docs.anynines.com
   dashboard:        https://a9s-logme2-dashboards.your-domain.com/service-instance/a89f3114-5e77-40a5-b3b0-34a9741f3cd5
   service broker:   logme2-service-broker
   
   This service is not currently shared.
   
   Showing status of last operation from service my-logme2-service...
   
   status:    create succeeded
   message:
   started:   2022-27-08T20:18:13Z
   updated:   2022-27-08T20:24:33Z
   
   bound apps:
   name          binding name   status             message
   my-app                       create succeeded

3. Extend the dashboard URL with a postfix /opensearch-dashboard. In the above example this would result in the URL https://a9s-logme2-dashboards.your-domain.com/service-instances/a89f3114-5e77-40a5-b3b0-34a9741f3cd5/opensearch-dashboard.

4. Open the URL in a browser and then authenticate on the OpenSearch Dashboards login page with your Service Key credentials:

5. Once your a9s LogMe2 Service Instance has received messages, the following page will be presented to you and you just need to click on the left 'Visualize & analyze' link.

6. On the 'Getting started with OpenSearch Dashboards' page you need to select the 'Add your data' button.

7. Then you can proceed by clicking the 'Create index pattern' button.

8. In the field 'Index pattern name', you need to enter fluentd-*. Once you entered that value, a message should appear that your index pattern matches a source. Click on 'Next step' to proceed.

9. In the second step of 'Create index pattern', you need to select '@timestamp' for the 'Time field'. Afterwards, click 'Create index pattern' button to conclude the initial setup.

Your service's logs appear on the Discover view of OpenSearch Dashboards:

It may take a few seconds until the messages appear in OpenSearch Dashboards.

Stop Streaming Logs to a9s LogMe2

To stop streaming an application's or a Service Instance's logs to the a9s LogMe2 Service Instance, the syslog key of the Service Instance's configuration can be overwritten.

Run cf update-service INSTANCE-NAME -c PARAMETERS-AS-JSON to update the syslog endpoint of the instance you don't want to monitor anymore. For this, you need to overwrite the value of the syslog key with an empty string.

cf update-service service-instance-to-monitor -c '{"syslog": []}'