This topic is about Microsatellites. If you installed Satellites previous to 4/06/2021, you are probably running legacy Satellites.

The Lightstep Microsatellite is available as an AMI in several AWS regions:

The AMI will start the Microsatellite binary automatically when an instance boots.

When creating instances, set user data to configure Microsatellites. If you are using the console, you can find user data under Configure Instance Details and Advanced Details. User data should be entered into the console as YAML-formatted text. You can use the template below and find detailed explanations and recommended settings here. Defaults are entered, but you can change them.

If you are happy with the default port numbers and don’t need TLS, you only need to modify the following settings:

  • satellite_type: flavor (be sure this is set to micro)

  • satellite_key
  • pool

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# Microsatellite Configuration
#
# This file describes all the required and optional fields to customize your Microsatellite configuration.
#
# ----------------------- SATELLITE TYPE ---------------------

# REQUIRED
satellite_type:
    flavor: micro


# ----------------------- AUTHENTICATION ---------------------
# REQUIRED: Satellite Key
satellite_key:

# ----------------------- DEBUGGING ---------------------
# HIGHLY RECOMMENDED: Microsatellite Pool Name
pool:
# HIGHLY RECOMMENDED: Microsatellite GUID
guid:

# ----------------------- MONITORING ---------------------
# OPTIONAL: Export statsd metrics for Microsatellite
# To enable Microsatellite metrics, uncomment the `statsd` header and relevant fields below.
#
# statsd:
#
#   REQUIRED: Host address for the statsd agent
#     Note: "localhost" may not work, use 127.0.0.1 instead
#     Uncomment the line below to set the statsd agent host address
#   host:
#
#   REQUIRED: Port number for the statsd agent
#     Uncomment the line below to set the port number for your statsd agent
#   port:
#
#   REQUIRED: Choose between statsd and dogstatsd metrics format
#     The following settings are mutually exclusive and you must set exactly one of them.
#     Uncomment one of the following lines to enable the desired format for metrics
#   export_statsd: true
#   export_dogstatsd: true
#
#   OPTIONAL: Add custom tags for dogstatsd metrics
#     This setting is only available when export_dogstatsd: true
#     Uncomment the following line to add one or more custom tags for dogstatsd metrics
#   dogstatsd_tags:
#
#
#   Note: Metrics exported by the Microsatellite are named as follows:
#       <prefix>.<satellite_prefix|client_prefix>.<metric_name>
#   You can use the set of optional fields below to customize the metric names, if desired.
#
#     All prefixes and tag names below should follow these rules, unless your metrics service provider supports additional characters:
#     - must start with a letter
#     - must only contain ASCII alphanumerics (lowercase recommended), underscores, and periods
#
#   OPTIONAL: Set a custom metric name prefix
#     The prefix is empty by default.
#     Uncomment the following line to set a custom metrics prefix
#   prefix: "lightstep"
#
#   OPTIONAL: Rename the Microsatellite and/or client metrics
#     The satellite_prefix field has a default value of "satellite", and will be included in the name of all
#     metrics that reflect Microsatellite behavior.
#     Uncomment the following line to set a custom prefix for Microsatellite metrics
#   satellite_prefix: "satellite"
#
#     The client_prefix field has a default value of "client", and will be included as part of the name for all metrics
#     that reflect the behavior of the Lightstep tracer client (these metrics are still exported via the Microsatellite).
#     Uncomment the following line to set a custom prefix for client metrics
#   client_prefix: "client"

# ----------------------- PORTS ---------------------
# Ports cannot be shared. All port numbers below must be unique.

# REQUIRED: Span Ingest ports
# At least one of the following ports must be set in order to handle incoming span traffic.

# REQUIRED: Plaintext Span Ingest Port
# This port accepts *unencrypted* span traffic.
plain_port: 8383

# OPTIONAL: Secure Span Ingest Port
# Uncomment the line below to enable the secure port.
# secure_port: 9393

# REQUIRED: Debug Port ("diagnostic")
diagnostic_port: 8000

# REQUIRED: Admin Ports: Health Checks / Diagnostics
# The values are flexible and can be set to different (unbound) port numbers as needed.
admin:
  # REQUIRED: Plaintext Admin Port
  plain_port: 8180
  
  # Uncomment the line below to enable the secure health check port.
  # secure_port: 9090

# ----------------------- TLS ---------------------
# OPTIONAL: TLS certificate path
# Required if using any of the SecurePorts in order to provide TLS termination at the Microsatellite.
# Uncomment the line below (and set appropriately) if using any of the secure ports above.
# tls_cert_prefix:

# -------------------MISC-------------------------
# OPTIONAL: Ingestion tags
# Uncomment the line below and add a comma-separated list of tag/value pairs. These tags and values are added to every span the Microsatellite ingests.
# ingestion_tags:

# OPTIONAL: Single project mode
# Uncomment the lines below if you are only running one project in Lightstep and you don't want to pass an access token from your tracer to your Microsatellite.
# disable_access_token_checking:
# project_name

# OPTIONAL: Sampling
# Uncomment the line below if you want the Microsatellite to downsample incomoming spans. When set to a value > 0, the Microsatellite will 
# keep 1 out of every N spans and discard the other N-1 spans. For example, when sample_one_in_n = 10, the Microsatellite will
# keep only 1 out of every 10 spans, or 10% of all spans. A value of 0 disables sampling and causes the Microsatellite
# to keep all spans.
# sample_one_in_n: 0

Follow these instructions to further validate your installation and troubleshoot any issues.

You configure your Lightstep tracers to communicate with your Microsatellites by providing their location. If you are using a single Microsatellite, you provide the DNS name or IP address of that Microsatellite. For more than one, use the name or address of the load balancer you’ve deployed. Find out how to do that in the language-specific Quick Start guides.

By default, client libraries use secure connections. If you’ve configured your Microsatellites to use plainport connections, you must configure your tracer appropriately.