To use the library for the first time in a given environment, complete this quick procedure:
SCOPE_HOMEdirectory, i.e., the directory from which AppScope should run in your environment.
SCOPE_HOME to the desired directory.
ubuntu@my_hostname:~/someuser/temp$ export SCOPE_HOME=/opt/appscope
SCOPE_HOME directory. (Here,
sudo is required because
opt is owned by root.)
ubuntu@my_hostname:~/someuser/temp$ sudo mkdir $SCOPE_HOME
scope extract) the contents of the AppScope binary into the
ubuntu@my_hostname:~/someuser/temp$ sudo ./scope extract $SCOPE_HOME Successfully extracted to /opt/appscope.
SCOPE_HOME contains the AppScope library (
libscope.so) and the config file (
ubuntu@my_hostname:~/someuser/temp$ ls -al $SCOPE_HOME total 20528 drwxr-xr-x 2 root root 4096 Jul 11 22:51 . drwxr-xr-x 5 root root 4096 Jul 11 22:51 .. -rwxr-xr-x 1 root root 9663240 Jul 11 22:51 libscope.so -rw-r--r-- 1 root root 35755 Jul 11 22:51 scope.yml ubuntu@my_hostname:~/someuser/temp$
Now you are ready to configure AppScope to instrument any application and output data to any existing tool via simple TCP protocols.
Depending on your use case and preferred way of working, this usually entails editing
scope.yml, and then setting environment variables while invoking the library.
How the library is loaded depends on the type of executable. A dynamic loader can preload the library (where supported), while AppScope can load static executables. Regardless of how the library is loaded, you get full control of the data source, formats, and transports.
For the default settings in the sample
scope.yml configuration file, see Config File, or inspect the most-recent file on GitHub.
To see the config file with comments omitted, run the following command:
egrep -v '^ *#.*$' scope.yml | sed '/^$/d' >scope-minimal.yml
This can help you get a clear idea of exactly how AppScope is configured, assuming you have previously read and understood the comments.
To use the library directly, you rely on the
LD_PRELOAD environment variable.
The following examples provide an overview of this way of working with the library. All the examples call the system-level
ps command, just to show how the syntax works.
For more, check out the Further Examples, which include both CLI and library use cases.
LD_PRELOADwith a Single Command
Start with this basic example:
LD_PRELOAD=./libscope.so ps -ef
This executes the command
ps -ef. But first, the OS's loader loads the AppScope library, as part of loading and linking the
Details of the
ps application's execution are emitted to the configured transport, in the configured format. For configuration details, see Env Vars and the Config File above.
LD_PRELOADwith Verbosity Specified
LD_PRELOAD=./libscope.so SCOPE_METRIC_VERBOSITY=5 ps -ef
This again executes the
ps command using the AppScope library. But it also defines the verbosity for metric extraction as level
5. (This verbosity setting overrides any config-file setting, as well as the default value.)
LD_PRELOADwith a Config File
LD_PRELOAD=./libscope.so SCOPE_HOME=/etc/scope ps -ef
This again executes the
ps command using the AppScope library. But it also directs the library to use the config file
LD_PRELOADwith a TCP Connection
LD_PRELOAD=./libscope.so SCOPE_EVENT_DEST=tcp://localhost:9999 SCOPE_CRIBL_ENABLE=false ps -ef
This again executes the
ps command using the AppScope library. But here, we also specify that events (as opposed to metrics) will be sent over a TCP connection to localhost, using port
9999. (This event destination setting overrides any config-file setting, as well as the default value.)
In this example, we'll add AppScope to the
httpd service, described by an
httpd.service file which contains an
/opt/appscopein this example):
mkdir /opt/appscope && cd /opt/appscope curl -Lo scope https://cdn.cribl.io/dl/scope/\ $(curl -L https://cdn.cribl.io/dl/scope/latest)/linux/scope && \ chmod 755 ./scope ./scope extract .
The result will be that the system uses
/opt/appscope/scope.yml to configure
LD_PRELOADenvironment variable to the
httpd.service file, edit the
/etc/sysconfig/httpd entry to include the following environment variables:
You can interpose the
libscope.so library into an AWS Lambda function as a Lambda layer. By default, Lambda functions use
lib as their
LD_LIBRARY_PATH, which makes loading AppScope easy.
Assuming that you have created one or more AWS Lambda functions, all you need to do is add the Lambda layer, then set environment variables for the Lambda function.
Start with one of the AWS Lambda Layers for AppScope that Cribl provides. You can obtain the AWS Lambda Layers and their MD5 checksums from the Cribl CDN.
AWS Lambda Layer for x86: https://cdn.cribl.io/dl/scope/1.2.2/linux/x86_64/aws-lambda-layer.zip
AWS Lambda Layer for ARM: https://cdn.cribl.io/dl/scope/1.2.2/linux/aarch64/aws-lambda-layer.zip
.md5to the file path.
ARM64, as appropriate, for Compatible architectures.
The AWS docs explain how to set environmental variables for Lambda functions. You'll need to enter the following AppScope environment variable settings in the AWS UI.
LD_PRELOAD gets your Lambda function working with AppScope.
SCOPE_EXEC_PATH is required for static executables (like the Go runtime).
To tell AppScope where to deliver events, the required environment variable depends on your desired Data Routing.
SCOPE_CRIBL_CLOUDis required for an AppScope Source in a Cribl.Cloud-managed instance of Cribl Stream. (Substitute your host and port values for the placeholders.)
Optionally, set additional environment variables as desired.
SCOPE_CONF_PATHensures that your Lambda function uses AppScope with the correct config file. (Edit the path if yours is different.)