libstapsdt

https://libstapsdt.readthedocs.io/en/latest/
Admin
libstapsdt is a C library for creating runtime USDT tracing probes on Linux.
Tokens:2,805
Snippets:34
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Complete libstapsdt Usage Example

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html

This example demonstrates the full lifecycle of using libstapsdt, from provider and probe creation to loading, firing, unloading, and destruction.

```c
#include <unistd.h>
#include <stdio.h>
#include <libstapsdt.h>

int main() {
  int i=1;
  SDTProvider_t *provider;
  SDTProbe_t *probe;

  provider = providerInit("myLittleProvider");
  probe = providerAddProbe(provider, "myLittleProbe", 1, uint64);

  if(providerLoad(provider) == -1) {
    printf("Something went wrong...\n");
    return -1;
  }

  while(i) {
    printf("Firing probe...\n");
    if(probeIsEnabled(probe)) {
      probeFire(probe, "I'm a runner!");
      printf("Probe fired!\n");
      i = 0;
    }
    sleep(1);
  }

  providerUnload(provider);
  providerDestroy(provider);

  return 0;
}

```

--------------------------------

### Run the libstapsdt Demo Program

Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html

Execute the libstapsdt demo program with specified provider and probe names. This helps in testing the installed library.

```bash
./demo PROVIDER_NAME PROBE_NAME

```

--------------------------------

### Build and Install libstapsdt from Source

Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html

Compile and install the libstapsdt library from its source code. This process includes building the library and updating the dynamic linker cache.

```bash
make
sudo make install
sudo ldconfig

```

--------------------------------

### Install libstapsdt on Ubuntu via PPA

Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html

Add the Sthima's Open Source Software PPA and install the libstapsdt packages. This is the recommended method for Ubuntu users.

```bash
sudo add-apt-repository ppa:sthima/oss
sudo apt-get update
sudo apt-get install libstapsdt0 libstapsdt-dev

```

--------------------------------

### Install libstapsdt Dependencies on Ubuntu

Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html

Install the necessary libelf dependency for building libstapsdt from source on Ubuntu. This is a prerequisite for the build process.

```bash
sudo apt install libelf1 libelf-dev

```

--------------------------------

### Systemtap SDT Probe Registration Example

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/internals.html

This C code demonstrates how to register a Systemtap SDT probe named 'Probe' to a provider named 'Provider' using the DTRACE_PROBE macro.

```c
#include <sys/sdt.h>

int main() {
  DTRACE_PROBE(Provider, Probe);
  return 0;
}

```

--------------------------------

### Build the libstapsdt Demo Program

Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html

Compile the provided demo program for libstapsdt. The executable will be generated in the current directory.

```bash
make demo  # Executable will be available at ./demo

```

--------------------------------

### providerInit

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Initializes a new SDTProvider_t with a given name. It creates the provider with all attributes correctly initialized. Returns a pointer to the new provider or NULL if an error occurs.

```APIDOC
## providerInit

### Description
Initializes a new SDTProvider_t with a given name. It creates the provider with all attributes correctly initialized. Returns a pointer to the new provider or NULL if an error occurs.

### Parameters
#### Path Parameters
- **name** (string) - The name of this provider

### Return Type
SDTProvider_t*

### Returns
A pointer to the new provider or NULL if an error occurs.
```

--------------------------------

### Provider and Probe Initialization

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html

Initializes a libstapsdt provider and registers a probe with specified arguments and types. Ensure the provider name and probe details are unique and appropriate for your use case.

```c
SDTProvider_t *provider;
SDTProbe_t *probe;

provider = providerInit("myLittleProvider");
probe = providerAddProbe(provider, "myLittleProbe", 1, uint64);

```

--------------------------------

### Trace libstapsdt Demo with bcc trace

Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html

Use the bcc trace tool to monitor probes from the libstapsdt demo program. This requires the process ID of the running demo.

```bash
sudo /usr/share/bcc/tools/trace -p $(pgrep demo) 'u::PROBE_NAME'

```

--------------------------------

### Loading the Provider

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html

Loads the libstapsdt provider, making its registered probes available for tracing. Error handling is crucial here; a return value of -1 indicates a failure.

```c
if(providerLoad(provider) == -1) {
  printf("Something went wrong...\n");
  return -1;
}

```

--------------------------------

### Elf Section and Note for Systemtap SDT Probes

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/internals.html

This output shows the Elf notes generated for Systemtap SDT probes, including provider name, probe name, location, base address, semaphore, and arguments.

```text
Displaying notes found at file offset 0x00001064 with length 0x0000003c:
  Owner                 Data size       Description
  stapsdt              0x00000028       NT_STAPSDT (SystemTap probe descriptors)
    Provider: Provider
    Name: Probe
    Location: 0x00000000004004da, Base: 0x0000000000400574, Semaphore: 0x0000000000000000
    Arguments: 

```

--------------------------------

### providerLoad

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Loads a provider, making all its registered probes available for tracing. Returns 0 on success, or a non-zero number on error. After loading, no new probes can be added, and the provider cannot be loaded again.

```APIDOC
## providerLoad

### Description
Loads a provider, making all its registered probes available for tracing. Returns 0 on success, or a non-zero number on error. After loading, no new probes can be added, and the provider cannot be loaded again.

### Parameters
#### Path Parameters
- **provider** (SDTProvider_t*) - The provider to be loaded

### Return Type
int

### Returns
A status code (0 means success, other numbers indicate error).
```

--------------------------------

### probeFire

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Fires a probe if it is available for tracing (i.e., if providerLoad() was called previously). Accepts any number of arguments that match the probe's expected arguments.

```APIDOC
## probeFire

### Description
Fires a probe if it is available for tracing (i.e., if providerLoad() was called previously). Accepts any number of arguments that match the probe's expected arguments.

### Parameters
#### Path Parameters
- **probe** (SDTProbe_t*) - The probe to be fired
- **...** (any) - Any number of arguments (must match the expected number of arguments for this probe)
```

--------------------------------

### providerAddProbe

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Adds a new SDTProbe_t to an existing SDTProvider_t. The probe is created with a given name, argument count, and argument types. Returns a pointer to the created probe or NULL if an error occurs.

```APIDOC
## providerAddProbe

### Description
Adds a new SDTProbe_t to an existing SDTProvider_t. The probe is created with a given name, argument count, and argument types. Returns a pointer to the created probe or NULL if an error occurs.

### Parameters
#### Path Parameters
- **provider** (SDTProvider_t*) - The provider where this probe will be created
- **name** (string) - The name of this probe
- **argCount** (int) - The number of arguments accepted by this probe
- **...** (SDTArgTypes_t) - Any number of arguments (number of arguments must match argCount)

### Return Type
SDTProbe_t*

### Returns
A pointer to the new provider or NULL if an error occurs.
```

--------------------------------

### providerDestroy

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Frees an SDTProvider_t and all its registered SDTProbe_t from memory.

```APIDOC
## providerDestroy

### Description
Frees an SDTProvider_t and all its registered SDTProbe_t from memory.

### Parameters
#### Path Parameters
- **provider** (SDTProvider_t*) - The provider to be freed from memory, along with its probes
```

--------------------------------

### providerUnload

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Unloads a provider, making its probes unavailable for tracing. Returns 0 on success, or a non-zero number on error. After unloading, new probes can be added to the provider again.

```APIDOC
## providerUnload

### Description
Unloads a provider, making its probes unavailable for tracing. Returns 0 on success, or a non-zero number on error. After unloading, new probes can be added to the provider again.

### Parameters
#### Path Parameters
- **provider** (SDTProvider_t*) - The provider to be unloaded

### Return Type
int

### Returns
A status code (0 means success, other numbers indicate error).
```

--------------------------------

### Unloading and Destroying Provider

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html

Unloads the libstapsdt provider and destroys it to free allocated resources. It is essential to call `providerUnload()` before `providerDestroy()` to prevent memory leaks and segmentation faults.

```c
providerUnload(provider);
providerDestroy(provider);

```

--------------------------------

### Conditional Probe Firing

Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html

Checks if a probe is enabled using `probeIsEnabled()` before firing it with `probeFire()`. This ensures probes are only activated when tracing is active, preventing unnecessary operations.

```c
while(i) {
  printf("Firing probe...\n");
  if(probeIsEnabled(probe)) {
    probeFire(probe, "I'm a runner!");
    printf("Probe fired!\n");
    i = 0;
  }
  sleep(1);
}

```

--------------------------------

### probeIsEnabled

Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html

Checks if a probe is currently being traced. Returns 1 if the probe is enabled, and 0 otherwise.

```APIDOC
## probeIsEnabled

### Description
Checks if a probe is currently being traced. Returns 1 if the probe is enabled, and 0 otherwise.

### Parameters
#### Path Parameters
- **probe** (SDTProbe_t*) - The probe to be checked

### Return Type
int

### Returns
1 if probe is enabled, 0 otherwise.
```
Tokens:
Raw