Updating

Changes in AppScope 1.0 affect some metric and event definitions, environment variables, and content (including default settings) in the scope.yml config file.

Note: By "version 1.0," we mean version 1.0.1 or newer. The AppScope team recommends using a version above 1.0.0, which contained an incomplete feature set.

To update a Maintenance Pre-Release (version 0.8.1 or older) to version 1.0, follow this general procedure:

• Familiarize yourself with the summary of changes below.
• If you use a config file, download the new config file from github, and read through it.

• Make a note of changes that affect anything on which your deployment depends, including:

  • Defaults that have changed.
  • Metrics or events whose structure or names have changed.
  • Environment variables that you use outside of the config file, that need to be used differently than before.

• Based on what you discover:

  • Update how you (plan to) use environment variables.
  • Edit the new config file (if you are using one).
  • Configure any destinations to which you're sending data from AppScope, or scripts that operate on the data, to work with the changed event and/or metrics.

Then, go ahead and update!

Performing the Update

You can update AppScope in place. First, download a fresh version of the binary. (This example assumes that you are running AppScope from /opt/scope, as described here. If you're running AppScope from a different location, adapt the command accordingly.)

curl -Lo /opt/scope https://s3-us-west-2.amazonaws.com/io.cribl.cdn/dl/scope/cli/linux/scope && chmod 755 /opt/scope

Then, to confirm the overwrite, verify AppScope's version and build date:

scope version

Summary of Changes in AppScope 1.0

This overview of changes should help you prepare to update AppScope.

Changes to Routing

New routing capabilities in AppScope 1.0 required the following changes:

• The cribl backend is now enabled by default, and its transport type now defaults to edge instead of tcp.
• A new environment variable, SCOPE_CRIBL_ENABLE, determines whether or not to send data to the cribl backend.
• When SCOPE_CRIBL_ENABLE is set to false, the default destination for the ldscope binary is tcp, as before.
• SCOPE_CRIBL or SCOPE_CRIBL_CLOUD now only define the cribl transport and destination.

• When the edge transport is used, ldscope and scope will search for a unix domain socket. The search tries the following locations, in order, only searching until a socket is found:

  • /var/run/appscope/appscope.sock
  • $CRIBL_HOME/state/appscope.sock
  • /opt/cribl/state/appscope.sock

• In the CLI, the -m or --metricdest, -e or --eventdest, and -c or --cribldest options all enable you to target either edge, unix, or tcp.

  • As before, the default destination for the CLI is the scope session directory in the local filesystem.

Learn more about routing here.

Changes to Events and Metrics

AppScope events and metrics are now rigorously defined in schemas found in /docs/schemas/. Metrics and events follow more consistent patterns overall. Changes that resolve inconsistencies include:

• All metric types and units are consistent.
• All durations are in milliseconds unless explicitly defined otherwise.
• Non-aggregated metrics no longer appear alongside aggregated metrics.
• All summarized metrics now have class: summary.
• Event dimension names are consistent, e.g., file_name is now file.
• id and _channel fields have been added, where previously missing.
• The data fields net_peer_port and net_host_port are now of type integer, for example:

{"type":"evt","id":"vm-curl-curl wttr.in","_channel":"118389477035177","body":{"sourcetype":"http","_time":1643997015.8988931,"source":"http.req","host":"vm","proc":"curl","cmd":"curl wttr.in","pid":112157,"data":{"http_method":"GET","http_target":"/","http_flavor":"1.1","http_scheme":"http","http_host":"wttr.in","http_user_agent":"curl/7.74.0","net_transport":"IP.TCP","net_peer_ip":"5.9.243.187","net_peer_port":80,"net_host_ip":"10.0.2.15","net_host_port":44214}}}

• The data field http_status_code used to be a string for HTTP/2 traffic. It is now an integer for both HTTP/1 and HTTP/2 traffic. For example:

`{"type":"evt","id":"vm-curl- --http2 -I https://nghttp2.org/","_channel":"118695329693352","body":{"sourcetype":"http","_time":1643997322.1907151,"source":"http.resp","host":"vm","proc":"curl","cmd":"curl --http2 -I https://nghttp2.org/","pid":112210,"data":{"http_flavor":"2.0","http_stream":1,"http_status_code":200,"http_status_text":"OK","http_response_content_length":6616,"net_transport":"IP.TCP","net_peer_ip":"139.162.123.134","net_host_ip":"10.0.2.15","net_peer_port":443,"net_host_port":35352,"http_client_duration":186,"http_host":"nghttp2.org","http_method":"HEAD","http_target":"/","http_user_agent":"curl/7.74.0”}}}`

Review the tables below to determine whether event or metric name changes affect your use of AppScope. (AppScope 1.0.0 has been omitted from the tables because it has been replaced by AppScope 1.0.1.)

Event Names that Changed in AppScope 1.0

Pre-GA	1.0.1
http-req	http.req
http-resp	http.resp
remote_protocol	net.app
net.dns.resp	dns.resp
net.dns.req	dns.req
net.dns.duration	dns.duration
fs.op.stat	fs.stat
fs.op.open	fs.open
fs.op.close	fs.close
fs.op.seek	fs.seek
net.conn_duration	net.duration
net.conn.open	net.open
net.conn.close	net.close

Metric Names that Changed in AppScope 1.0

Pre-GA	1.0.1
fs.op.stat	fs.stat
fs.op.open	fs.open
fs.op.close	fs.close
fs.op.seek	fs.seek
http.requests	http.req
http.request.content_length	http.req.content_length
http.response.content_length	http.resp.content_length
http.server.duration	http.duration.server
http.client.duration	http.duration.client
net.dns	dns.req
net.dns.duration	dns.duration
net.conn.duration	net.duration
net.conn_duration	net.duration