Enable telemetry

[nicholaspcr]

Summary

References #6081

Enables telemetry for the Stack and the CLI, this sets the default value to true and it defines the value of the target at which the telemetry information is sent.

The main points of this PR are:

• the changelog message
• the documentation PR linked
• the log messages contents
  • one for CLI
  • one for IS

Changes

• Change the pkg used for generating the uuid for telemetry/cli. Has the same effect since both use the RFC 4122 but Google's package should be one used on my opinion.
• Add log INFO messages for when telemetry is enable on CLI and/or IS.
• Add Changelog.md message introducing telemetry to users.

Testing

• Manual tests for the log messages
• I validated with the already deployed collector that the messages sent by CLI and IS are being received and plotted on Grafana.

Regressions

As this is a new feature, there aren't any regressions that I can imagine but this is the last change to have breaking changes.

For example the current message structure works around the concept that each field on the main json body represents a data collected in general, it might be interesting to encapsulate a bit more since we plan to add telemetry in other places, for example:

• Current:

{
  "message": {
    "uid": "",
    "os": {
      "operating_system": "linux",
      "arch": "amd64",
      "binary_version": "3.27.0-dev",
      "golang_version": " go1.20.7"
    },
    "cli": null,
    "entities_count": { 
      // ... 
    }
  }
}

• A bit more encapsulated:

{
  "message": {
    "uid": "",
    "os": {
      "operating_system": "linux",
      "arch": "amd64",
      "binary_version": "3.27.0-dev",
      "golang_version": " go1.20.7"
    },
    "cli": null,
    "is": {
      "entities_count": { // ... },
      // ...
    }
  }
} 

Might be a bit late for that but since its not a breaking change yet and only implies in small changes in here and in the lambda code its worth considering. @adriansmares @KrishnaIyer

Notes for Reviewers

1. Documentation PR can be found in here.
2. In regards to the steps to tests this feature I believe its more productive to write them after the discussion around the point made in the regressions section.
3. Regarding the changes made on:
   

   lorawan-stack/pkg/telemetry/exporter/config.go

   Line 37 in 44951fe

   UIDElements []string `name:"uid-elements" description:"Elements that will be used to generate the UID"` // nolint:lll

   
   This allows users to set their own values used to generate the hash, allowing them to disassociate their console URLs and still contribute telemetry data.

Checklist

• Scope: The referenced issue is addressed, there are no unrelated changes.
• Compatibility: The changes are backwards compatible with existing API, storage, configuration and CLI, according to the compatibility commitments in README.md for the chosen target branch.
• Documentation: Relevant documentation is added or updated.
• The steps/process to test this feature are clearly explained including testing for regressions.
• Changelog: Significant features, behavior changes, deprecations and fixes are added to CHANGELOG.md.
• Commits: Commit messages follow guidelines in CONTRIBUTING.md, there are no fixup commits left.

[adriansmares]

Might be a bit late for that but since its not a breaking change yet and only implies in small changes in here and in the lambda code its worth considering. @adriansmares @KrishnaIyer

For now I would keep the structure as is. We can always change it later on and handle different formats in the collector.

[adriansmares]

LGTM. Please fix these small nits.

[KrishnaIyer]

Nothing more to add.

[nicholaspcr]

Writing it here the steps to test the telemetry feature on the CLI and in the Stack.

---

Stack:

1. Failure on Telemetry enabled
   Add the following to the Stack's configuration:

telemetry:
  enable: true
  entity-count-telemetry:
    enable: true
    interval: 10s
  num-consumers: 1
  target: "http://localhost:8080"

Obs: Don't have anything running on :8080

When starting the Stack you should see:

INFO    Setting up Identity Server
INFO    Identity Server telemetry is enabled. Check the documentation for more information on what is collected and how to disable it   {"documentation_url": "https://www.thethingsindustries.com/docs/reference/telemetry/identity_server", "namespace": "identityserver"}

And after a few seconds you should see the following:

WARN    Failed to execute task from queue       {"error": "Post \"http://localhost:8080\": dial tcp 127.0.0.1:8080: connect: connection refused", "id": "entity-count-task", "namespace": "identityserver"}

Then after 10 seconds you should see the same message again.

2. Success on Telemetry enabled
   When using the default Stack configuration with TTN_LW_LOG_LEVEL="debug",
   Add the following to the Stack's configuration:

telemetry:
  enable: true
  entity-count-telemetry:
    enable: true
    interval: 10s
  num-consumers: 1
  target:  "https://telemetry.thethingsstack.io/collect"

You should see the following logs:

INFO    Setting up Identity Server
DEBUG   Run database query      {"duration": 0.003024, "namespace": "db", "operation": "SELECT", "query": "SELECT VERSION()"}
DEBUG   Run database query      {"duration": 0.002181, "namespace": "db", "operation": "SHOW", "query": "SHOW SERVER_VERSION"}
INFO    Identity Server telemetry is enabled. Check the documentation for more information on what is collected and how to disable it   {"documentation_url": "
https://www.thethingsindustries.com/docs/reference/telemetry/identity_server", "namespace": "identityserver"}
DEBUG   Add task to queue       {"namespace": "identityserver", "task": "entity-count-task"}
DEBUG   Register task callback  {"namespace": "identityserver", "task": "entity-count-task"}
DEBUG   Start telemetry queue dispatcher        {"namespace": "identityserver"}
DEBUG   Start telemetry queue consumers {"namespace": "identityserver"}
... 
// some log messages
...
DEBUG   Collected entity count telemetry data   {"message": {"uid":"m64Jv5T3Bqnxz3tSgOAYD0w25UqWwP5DgIsuKbS0g5dBQkA8ZEHwlV1iDoKgjeF7uE3dt+3SDMdANJ41xDZqag==","
os":{"operating_system":"linux","arch":"amd64","binary_version":"3.27.0-dev","golang_version":"go1.21.0"},"cli":null,"entities_count":{"gateways":{"total":0,"g
ateways_by_frequency_plan_id":{}},"end_devices":{"total":0,"activate_end_devices":{"total":0,"last_day":0,"last_week":0,"last_month":0}},"applications":{"total
":0},"accounts":{"users":{"standard":0,"admin":1},"organizations":{"total":0}}}}, "namespace": "identityserver"}

The contents of this message have to match the values present in the database, meaning that if you created 10 applications the values of entities_count.applications.total should be 10. I would recommended creating a range of diverse entities, like devices that are active, gateways with different frequency plans and validate if the correct amount show on the debug log.

3. Telemetry disabled
   Add the following to the Stack's configuration:

telemetry:
  enable: false
  entity-count-telemetry:
    enable: true
    interval: 10s
  num-consumers: 1
  target: "http://localhost:8080"

This by itself should stop all the telemetry procedures, so when running the Stack you should not see any of the messages listed on the first test item, such as:

INFO    Setting up Identity Server
INFO    Identity Server telemetry is enabled. Check the documentation for more information on what is collected and how to disable it   {"documentation_url": "https://www.thethingsindustries.com/docs/reference/telemetry/identity_server", "namespace": "identityserver"}

4. Telemetry enabled but specific procedures are disabled
   Currently we only have one telemetry process but subsequent processes will also have an option to disable them specifically.
   Enable DEBUG logs and add the following to the Stack's configuration:

telemetry:
  enable: true
  entity-count-telemetry:
    enable: false
    interval: 10s
  num-consumers: 1
  target: "http://localhost:8080"

With this configuration you should still see the logs informing that the telemetry is enabled but there should not be any message regarding the Collected entity count telemetry data. Should be something similar to the following:

INFO    Setting up Identity Server
DEBUG   Run database query      {"duration": 0.003024, "namespace": "db", "operation": "SELECT", "query": "SELECT VERSION()"}
DEBUG   Run database query      {"duration": 0.002181, "namespace": "db", "operation": "SHOW", "query": "SHOW SERVER_VERSION"}
INFO    Identity Server telemetry is enabled. Check the documentation for more information on what is collected and how to disable it   {"documentation_url": "
https://www.thethingsindustries.com/docs/reference/telemetry/identity_server", "namespace": "identityserver"}
DEBUG   Add task to queue       {"namespace": "identityserver", "task": "entity-count-task"}
DEBUG   Register task callback  {"namespace": "identityserver", "task": "entity-count-task"}
DEBUG   Start telemetry queue dispatcher        {"namespace": "identityserver"}
DEBUG   Start telemetry queue consumers {"namespace": "identityserver"}

// UNDER NO CIRCUMSTANCES THERE COULD BE A LOG MESSAGE FOR `Collected entity count telemetry data`

---

CLI

The CLI doesn't have a configurable interval for sending telemetry data. Before each test case, you will have to delete the file used to store when was the last time a telemetry message was sent. The file itself is stored in the Operating system's cache folder, where that might be on your system is detailed below:

// On Unix systems, it returns $XDG_CACHE_HOME as specified by
// https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html if
// non-empty, else $HOME/.cache.
// On Darwin, it returns $HOME/Library/Caches.
// On Windows, it returns %LocalAppData%.
// On Plan 9, it returns $home/lib/cache.

Most likely if you are on Linux it will be on $HOME/.cache/ttn-lw-cli/telemetry.yml

In addition to that, in all the following test cases the CLI's command used for testing is non specific, meaning that it should work if all the commands. I suggest trying to test it with different commands in order to ensure that this is valid, a few example are: login, gtw list, app list, dev create.

1. Failure on Telemetry enabled
   Add the following to the CLI's configuration:

telemetry:
  enable: true
  target: "http://localhost:8080"

There should be a failure message in the DEBUG log, like the following:

INFO    Telemetry is enabled. Check the documentation for more information on what is collected and how to disable it   {"documentation_url": "https://www.thethingsindustries.com/docs/reference/telemetry/cli"}
DEBUG   Failed to send telemetry information    {"error": "Post \"http://localhost:8080\": dial tcp 127.0.0.1:8080: connect: connection refused"}

2. Success on Telemetry enabled
   Delete the cache file and run the CLI with the default configuration. You should see the following logs:

INFO    Telemetry is enabled. Check the documentation for more information on what is collected and how to disable it   {"documentation_url": "https://www.thethingsindustries.com/docs/reference/telemetry/cli"}
...
INFO    Sent telemetry information

3. Telemetry disabled
   Add the following to the CLI's configuration:

telemetry:
  enable: false
  target: "http://localhost:8080"

Enable DEBUG logs in order to validate that an error log is not shown (meaning that no telemetry message POST is performed). You should not see any of the logs mentioned in the previous test items.