Microsatellite configuration parameters

Microsatellites aren’t supported for organizations hosted in the EU data center.

Installation and configuration of Cloud Observability Microsatellites vary, depending on if you’re installing to Docker, AWS/AMI, or Debian/Ubuntu, but all share the same configuration parameters. This topic describes each of these parameters. Read these topics for specific installation procedures, examples, and templates that you can use:

If the default port numbers work for you and you don’t require TLS, you need to modify only these parameters:

satellite_type: flavor (AWS/AMI only: be sure this is set to micro)
satellite_key
pool

Required parameters and highly recommended parameters are noted; all others are optional. Examples are shown using YAML files for Debian, Ubuntu, or AMI, and environment variables for Docker without Helm or a YAML file if using a Helm chart.

We prioritize Microsatellite configuration values as follows:
1. Any values found in flags are used if present.
2. Any values found in the file designated by the collector_base_config flag if present.
3. Any values found in the environment are used if present.
4. Any values found in the file designated by the COLLECTOR_BASE_CONFIG environment variable if present.

satellite_type

Needed for AWS/AMI only

Set this to micro

Start tabs

Debian/Ubuntu/AMI

satellite_type:
  flavor: micro

Docker Env Vars

-e COLLECTOR_SATELLITE_TYPE_FLAVOR=micro

Docker with Helm

satellite_type:
  flavor: micro

End code tabs

Authentication

These parameters allow your Microsatellites to communicate with the Cloud Observability platform.

satellite_key

REQUIRED

This value authorizes a Microsatellite to communicate with the platform for span reporting. You can find or generate your Satellite key here. Copy and paste the key as the value for this parameter. Satellite keys expire after one year. You’ll need to replace this value when you generate a new one.

Start tabs

Debian/Ubuntu/AMI

satellite_key: your-satellite-key

Docker Env Vars

-e COLLECTOR_SATELLITE_KEY=your-satellite-key

Docker with Helm

satelliteKey: "your-satellite-key"
# OR if using a Kubernetes secret key
collector_satellite_key_secret_name: "your-satellite-key"
collector_satellite_key_secret_key: "your-satellite-key-secret"

End code tabs

Debugging

These parameters create IDs for your Microsatellites and pools for easy debugging.

pool

HIGHLY RECOMMENDED

A user-defined, human-readable name for this Microsatellite pool to facilitate troubleshooting. Cloud Observability uses this parameter to segment your traffic from other customers in metrics and logs. It is also displayed in Cloud Observability as the Microsatellite pool name on the Satellite Pool Report page.

Microsatellite pools appear on the Satellite Pools page.

Guidelines:

DO use different names for Microsatellite pools that serve distinct Cloud Observability projects.
DO use different pool names for Microsatellites of different machine sizes or configuration settings. Try to keep individual instances within pools uniform.
DO use different names for Microsatellite pools in different regions.
DO use separate Microsatellite pool names for separate projects within Cloud Observability. This enables finer-grained tuning and optimization.

Start tabs

Debian/Ubuntu/AMI

pool: production-canary

Docker Env Vars

-e COLLECTOR_POOL=production-canary

Docker with Helm

collector_pool: rancher-satellite-pool

End code tabs

guid

HIGHLY RECOMMENDED

A user-defined, human-readable name for this Microsatellite instance. This ID is used to assist with matching Microsatellite information in Cloud Observability with instances running in your environment. The GUID allows you to identify individual Microsatellites within a pool. It’s displayed on the Satellites page when viewing a list of Microsatellites in a particular pool.

The GUID does not need to be the same as the AWS instance ID.

Satellite Details tab shows a sample Satellite GUID.

Guidelines:

DO provide a globally unique identifier.
DO use a value that maps directly to an instance in your environment.

Start tabs

Debian/Ubuntu/AMI

pool: ec2-19-211-35-1.compute-1.amazonaws.com
guid: 999.9.9.9

Docker Env Vars

-e COLLECTOR_POOL=production-canary
-e COLLECTOR_GUID=999.9.9.9

Docker with Helm

collector_pool: rancher-satellite-pool
guid: 999.9.9.9

End code tabs

Monitoring

Microsatellites can optionally export a set of StatsD-compatible metrics that allow you to monitor key indicators of a Microsatellite’s health. Read Understand StatsD Reporting Metrics for more info about Microsatellite monitoring and the metrics you can monitor.

statsd

REQUIRED if enabling monitoring

host

REQUIRED if enabling monitoring

This parameter sets the host for the StatsD agent.

Using localhost may not work. Use 127.0.0.1 instead.

Start tabs

Debian/Ubuntu/AMI

statsd:
  host: 127.0.0.1

Docker Env Vars

-e COLLECTOR_STATSD_HOST=127.0.0.1

End code tabs

port

REQUIRED if enabling monitoring

Port number for the StatsD agent.

Start tabs

Debian/Ubuntu/AMI

port: 8125

Docker Env Vars

-e COLLECTOR_STATSD_PORT=8125

End code tabs

export_statsd or export_dogstatsd

REQUIRED if enabling monitoring

You can export metrics to either StatsD or to Datadog. You can only set one of them. The StatsD export generates metrics in basic StatsD format and does not support any tags. The Datadog export generates metrics compatible with Datadog, with two default tags:

lightstep_project: Holds the Cloud Observability project name
satellite_type: Shows the type of Satellite reporting: either full or micro.

You can also add custom tags.

Start tabs

Debian/Ubuntu/AMI

export_statsd: true
# OR
export_dogstatsd: true

Docker Env Vars

-e COLLECTOR_STATSD_EXPORT_STATSD=true
# OR
-e COLLECTOR_STATSD_EXPORT_DOGSTATSD=true

End code tabs

dogstatsd_tags

OPTIONAL if using Datadog for monitoring

These are tags used by Datadog when reporting metrics.
All tags must:

Start with a letter
Must only contain ASCII alphanumerics (lowercase recommended), underscores, and periods

Start tabs

Debian/Ubuntu/AMI

dogstats_tags: "pool:us-west-1,canary:true"

Docker Env Vars

-e COLLECTOR_STATSD_DOGSTATSD_TAGS="pool:us-west-1,canary:true"

End code tabs

prefix

OPTIONAL

Metrics exported by the Microsatellite are named as follows: <prefix>.<satellite_prefix|client_prefix>.<metric_name>

By default, the prefix is empty. You can add this custom prefix to have it prepended to the name of all metrics.

All prefixes must:

Start with a letter
Only contain ASCII alphanumerics (lowercase recommended), underscores, and periods

General guideline:
Set the prefix to lightstep, so you know that these are the Microsatellite metrics.

Start tabs

Debian/Ubuntu/AMI

prefix: "lightstep"

Docker Env Vars

-e COLLECTOR_STATSD_PREFIX=lightstep

End code tabs

satellite_prefix

OPTIONAL

Metrics exported by the Microsatellite are named as follows: <prefix>.<satellite_prefix|client_prefix>.<metric_name>

The satellite_prefix field has a default value of satellite and is included in the name of all metrics that reflect Microsatellite behavior. You can change that value.

Start tabs

Debian/Ubuntu/AMI

satellite_prefix: "satellite-canary"

Docker Env Vars

-e COLLECTOR_STATSD_SATELLITE_PREFIX=satellite-canary

End code tabs

client_prefix

OPTIONAL

Metrics exported by the Microsatellite are named as follows: <prefix>.<satellite_prefix|client_prefix>.<metric_name>

The client_prefix field is used to identify the tracer and has a default value of client. It’s included in the name of all metrics that reflect the Cloud Observability tracer behavior (as reported by the Microsatellite). You can change that value.

Start tabs

Debian/Ubuntu/AMI

client_prefix: "client-via-canary"

Docker Env Vars

-e COLLECTOR_STATSD_CLIENT_PREFIX=client-via-canary

End code tabs

Ports

These parameters configure the ports your tracers use to communicate with your Microsatellites.

Ports can’t be shared and must be unique.

Microsatellites support four reporting mechanisms:

JSON over HTTP
Thrift over HTTP
Protocol buffers over HTTP
Protocol buffers over gRPC (HTTP/2)

span ingest

REQUIRED

Set at least one of these ports to handle incoming span traffic.

plain_port

This port accepts unencrypted span traffic.

Start tabs

Debian/Ubuntu/AMI

plain_port: 8383

Docker Env Vars

-e COLLECTOR_PLAIN_PORT=port -p port:port

Docker with Helm

plain_port: 8383

End code tabs

secure_port

This port accepts encrypted span traffic.

Start tabs

Debian/Ubuntu/AMI

secure_port: 9393

Docker Env Vars

-e COLLECTOR_SECURE_PORT=port -p port:port

Docker with Helm

secure_port: 9393

End code tabs

diagnostic_port

REQUIRED

This port serves the /diagnostics endpoint, which provides a status page with diagnostic information about the Microsatellite.

The value is flexible and can be set to a different (unbound) port number as needed. The default is 8000.

Start tabs

Debian/Ubuntu/AMI

diagnostic_port: 8000

Docker Env Vars

-e COLLECTOR_DIAGNOSTIC_PORT=port -p port:port

Docker with Helm

diagnostic_port: 8000

End code tabs

admin

REQUIRED

These ports (plain_port and secure_port) are used for health checks and diagnostics and serve the following endpoints:

/_ready: Used by load balancers for health checks. A 200 (OK) response indicates that the Microsatellite is both responding and able to handle incoming span traffic.
/_live: Used by orchestration tools like Kubernetes for liveness checks. A 200 (OK) response indicates that the Microsatellite is alive and responding, and you should not terminate the instance. However, it makes no promises about Microsatellite health. It may be temporarily overloaded and not accepting spans.

plain_port

REQUIRED

This port is the plaintext admin port and must always be set to an open port number for Microsatellite diagnostics to work properly. This port is also the destination for unencrypted health/readiness checks from a load balancer or orchestration framework.

secure_port

OPTIONAL

This port is only required if sending encrypted health/readiness checks to the Microsatellite (this is not common). If set to a non-zero value, the tls_cert_prefix parameter must also be set.

Start tabs

Debian/Ubuntu/AMI

admin:
  plain_port: 8180
  secure_port: 9090

Docker Env Vars

-e COLLECTOR_ADMIN_PLAIN_PORT=port -p port:port
-e COLLECTOR_ADMIN_SECURE_PORT -p port:port

Docker with Helm

admin_plain_port: 8180
admin_secure_port: 9090

End code tabs

TLS

A TLS value is required if you are using any secure ports to provide TLS termination at the Microsatellite. When setting a secure port, you must make certificates available to the Microsatellite. Copy TLS certificates and a key to PATH.bundle.pem and PATH.key.pem and set the TLS certificate prefix to PATH. The prefix may contain /. The bundle file must contain a complete chain of certificates from a root (for example, PATH.bundle.pem is often the concatenation of .crt and .ca-bundle).

tls_cert_prefix

REQUIRED IF USING SECURE PORTS

This string gives the file path prefix for certificate files used in serving TLS connections on the Microsatellite.

This example assumes the certificate is located at /root/certs/mydomain.bundle.pem and /root/certs/mydomain.key.pem

Start tabs

Debian/Ubuntu/AMI

tls_cert_prefix: /root/certs/mydomain

Docker Env Vars

-e COLLECTOR_TLS_CERT_PREFIX=/root/certs/mydomain

Docker with Helm

tls_cert_prefix: "/root/certs/mydomain"

End code tabs

Single Project Mode

When you dedicate a Microsatellite pool to each project (for example, if you have separate projects for your dev and production environments and they each have a separate pool reporting to them), then you no longer need to pass in an access token.

General guideline: Create separate projects for each environment and then using single-project mode to dedicate a Microsatellite pool for each.

disable_access_token_checking

OPTIONAL

Set this to true to dedicate a separate Microsatellite pool for a project. You will no longer need to pass your access token from your tracer to your Microsatellites.

project_name

REQUIRED IF DISABLE_ACCESS_TOKEN_CHECKING IS SET TO TRUE

The name of the project in Cloud Observability.

Start tabs

Debian/Ubuntu/AMI

disable_access_token_checking: true
project_name: "My Project"

Docker Env Vars

COLLECTOR_DISABLE_ACCESS_TOKEN_CHECKING=true
COLLECTOR_PROJECT_NAME=${PROJECT}

Docker with Helm

disable_access_token_checking: true
project_name: "My Project"

End code tabs

Ingestion Tags

Ingestions tags are static tags added to all spans received by the Microsatellite.

ingestion_tags

OPTIONAL

A comma-separated name/value pair list of tags/values. These tags are static - the same tag and value is applied to every span the Microsatellite receives.

Start tabs

Debian/Ubuntu/AMI

ingestion_tags: myTagKey1:myTagValue1,myTagKey2:myTagValue2

Docker Env Vars

COLLECTOR_INGESTION_TAGS=myTagKey1:myTagValue1,myTagKey2:myTagValue2

Docker with Helm

collector_ingestion_tags: "myTagKey1:myTagValue1,myTagKey2:myTagValue2"

End code tabs

Receivers

When you use an OpenTracing auto-installer for instrumentation, you may end up with non human-readable operation names, or operation names that don’t make sense. This can happen because the auto-installer is getting the name from a parameter in Datadog (the original owner of the installer) that might not be appropriate for your language. You can set that parameter to different values to see if that results in better operation names.

You can use either the resource or the name parameter, or both.

Which to use (or if using the both, the order to use) depends on the language of the installer. Refer to the Datadog docs for more info.

operation_name_extractors

OPTIONAL

Set the parameter to either resource, name, or both. If you set both, the order of the values matters. Cloud Observability tries to extract a name from the first variable value. If one isn’t found, it looks for the second value and uses that.

This parameter can only be used with YAML configuration.

Start tabs

Debian/Ubuntu/AMI

receivers:
  datadog:
    operation_name_extractors:
  	  - resource
  	  - name

End code tabs

Sampling

By default, Microsatellites collect 100% of the trace data emitted by your instrumentation. If you wish to reduce the number of spans sent to the platform for cost reasons, you can configure your Microsatellites to sample data.

If you decide to use this parameter, you will lose data. Microsatellites base sampling on trace_id to ensure that only full traces are sent. Spans in the same trace will either all be sent or all be dropped. Stream statistics remain accurate.

sample_percent

Available on Microsatellite release 2022-04-28_17-39-22z and later.

OPTIONAL (should be used only when necessary)

This parameter allows you to send only a percentage of span data to the platform. When this parameter is set to a value greater than 0, the Microsatellite will send that percentage of spans. For example, if sample_percent is set to 90, the Microsatellite will send 90% of spans and omit 10%.

This setting must be the same on all Microsatellites in the pool to avoid broken traces.

Start tabs

Debian/Ubuntu/AMI

sample_percent: 90

Docker Env Vars

COLLECTOR_SAMPLE_PERCENT=90

Docker with Helm

sample_percent: 90

End code tabs

Use the API to set sampling

If you want to control sampling programmatically, you can use the Cloud Observability API to set the sample_percent parameter.

Setting the sampling parameter using the API takes precedence over setting it in the configuration file. If you want to control sampling using the config file, do not also set it using the API.
Changing the value using the API doesn’t require a restart. Changes take a few minutes to propagate.

You will need an API key to access the API. You will also need to know the Cloud Observability organization and project name to make the request. Find that information in Personal settings and Cloud Observability’s sidebar.

Set the parameter

Set the sample_percent parameter

curl --location --request POST 'https://api.lightstep.com/public/v0.2/<YOUR_ORGNAIZATION>/projects/<PROJECT_NAME>/sampling-percent' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \
--data-raw '{
   "data": {
       "attributes": {
           "sample_percent": <VALUE>
       }
   }
}'

To turn off sampling, set the parameter to 100.

Get the parameter

Get the sample_percent parameter

curl --location --request GET 'https://api.lightstep.com/public/v0.2/<YOUR_ORGNAIZATION>/projects/<PROJECT_NAME>/sampling-percent' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \

sample_one_in_n

Deprecated as of Microsatellite release 2022-04-22_21-58-06Z

OPTIONAL (should be used only when necessary)

This parameter allows you to send only a percentage of span data to the platform. When this parameter is set to a value greater than 0, the Microsatellite will send 1 out of every N spans. For example, if sample_one_in_n is set to 10, the Microsatellite will send only 1 out of every 10 spans, or 10% of all spans.

This setting must be the same on all Microsatellites in the pool to avoid broken traces.

Start tabs

Debian/Ubuntu/AMI

sample_one_in_n: 10

Docker Env Vars

COLLECTOR_SAMPLE_ONE_IN_N=10

Docker with Helm

sample_one_in_n: 10

End code tabs

Use the API to set sampling

Deprecated as of Microsatellite release 2022-04-22_21-58-06Z

If you want to control sampling programmatically, you can use the Cloud Observability API to set the sample_one_in_n parameter.

Setting the sampling parameter in the configuration file takes precedence over setting it using the API. If you want to control sampling using the API, do not also set it in the configuration file.

Set the parameter

Set the sample_one_in_n parameter

curl --location --request POST 'https://api.lightstep.com/public/v0.2/<YOUR_ORGNAIZATION>/projects/<PROJECT_NAME>/sampling-rate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \
--data-raw '{
   "data": {
       "attributes": {
           "sample_one_in_n": <VALUE>
       }
   }
}'

To turn off sampling, set the parameter to 1.

Get the parameter

Get the sample_one_in_n parameter

curl --location --request GET 'https://api.lightstep.com/public/v0.2/<YOUR_ORGNAIZATION>/projects/<PROJECT_NAME>/sampling-rate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \

Microsatellite configuration parameters

satellite_type

Authentication

satellite_key

Debugging

pool

guid

Monitoring

statsd

host

port

export_statsd or export_dogstatsd

dogstatsd_tags

prefix

satellite_prefix

client_prefix

Ports

span ingest

plain_port

secure_port

diagnostic_port

admin

plain_port

secure_port

TLS

tls_cert_prefix

Single Project Mode

disable_access_token_checking

project_name

Ingestion Tags

ingestion_tags

Receivers

operation_name_extractors

Sampling

sample_percent

Use the API to set sampling

Set the parameter

Get the parameter

sample_one_in_n

Use the API to set sampling

Set the parameter

Get the parameter

See also