From 94f80a288b2ae65acb4444a2a464906dc55495e1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 19 Jan 2026 19:08:22 +0000 Subject: [PATCH 1/3] Initial plan From 853dd58c4c216c31e0e1aa263a0a6069a2b488ed Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 19 Jan 2026 19:14:42 +0000 Subject: [PATCH 2/3] Document detailed limitations in README Co-authored-by: plengauer <100447901+plengauer@users.noreply.github.com> --- README.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9848d40411..a3083ec064 100644 --- a/README.md +++ b/README.md @@ -264,7 +264,30 @@ You can configure the underlying SDK with the same variables as any other OpenTe Flags that are marked as `stable` are tested and verified in tests and real-world scenarios. Flags marked as `experimental` are new features that are tested but still lack long-term verification in real-world applications. They will eventually reach `stable` or `unsafe`. Flags marked as `unsafe` have implicit assumptions about the nature of the instrumented scripts and will therefore never reach `stable`. ## Limitations -Currently, we do not support restricted mode in shells (`set -r`). + +While OpenTelemetry for shell provides comprehensive automatic instrumentation, there are some technical limitations to be aware of: + +### Shell Functions Without the `function` Keyword +Shell functions can be defined in two ways: using the `function` keyword (`function mycommand() { ... }`) or without it (`mycommand() { ... }`). When a function is defined without the `function` keyword and its name collides with an actual command on the system (e.g., defining `curl() { ... }` when `/usr/bin/curl` exists), the instrumentation system may not correctly distinguish between the function and the command. This is because the aliasing mechanism used for auto-instrumentation relies on command type detection, which can be ambiguous in these cases. + +**Workaround:** Use the `function` keyword when defining functions, or choose function names that don't collide with system commands. Alternatively, use `otel_observe` to manually instrument the function calls. + +### File Descriptor Conflicts +The instrumentation uses file descriptor 7 as a communication channel to the OpenTelemetry SDK backend. If your script explicitly uses file descriptor 7 for its own purposes (e.g., `exec 7>myfile.txt`), this will interfere with OpenTelemetry's internal communication and may cause telemetry data to be lost or written to the wrong location. + +**Workaround:** Avoid using file descriptor 7 in your scripts. If you must use a specific file descriptor, choose a different number (e.g., 8, 9, or higher). You can also override the file descriptor used by OpenTelemetry by setting the `OTEL_REMOTE_SDK_FD` environment variable to a different number before sourcing the instrumentation. + +### PID Tracking for Background Processes +When commands are instrumented, they are wrapped in shell functions rather than being executed directly. This means that if you save the PID of a background process (using `$!`) and later try to kill it, you may end up killing the instrumentation wrapper subshell instead of the actual command. This can result in the command continuing to run even though you attempted to terminate it. + +**Workaround:** Instead of relying on `$!` immediately after launching a background command, use `ps` and `grep` to find the actual process by its command name and then use `kill ` with the specific numeric PID. For example: `pid=$(ps -o pid,comm | grep mycommand | grep -v grep | awk '{print $1}')` followed by `kill $pid`. Alternatively, implement proper process tracking using PID files or other inter-process communication mechanisms. + +### Restricted Mode +Shells running in restricted mode (`set -r`) are not supported. The instrumentation requires the ability to modify the shell environment, set aliases, and execute arbitrary commands, which are prohibited in restricted mode. + +### Additional Known Limitations +- Shell functions (as mentioned above) are not automatically instrumented. Use `otel_observe` to manually instrument function calls. +- Commands called via absolute or relative paths (e.g., `/bin/cat` or `./mycommand`) are not automatically instrumented by default. Use `otel_observe` or enable `OTEL_SHELL_CONFIG_INSTRUMENT_ABSOLUTE_PATHS=TRUE` (experimental) to instrument these commands. ## Traces The API described below is for manually creating and customizing spans. We recommend to do this only if the automatic instrumentation is not sufficient. From 06921b8550a39530b26ae69204acb83d36205638 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 19 Jan 2026 19:45:33 +0000 Subject: [PATCH 3/3] Reorder limitations and split into separate sections per feedback Co-authored-by: plengauer <100447901+plengauer@users.noreply.github.com> --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a3083ec064..ac2f04de7e 100644 --- a/README.md +++ b/README.md @@ -267,6 +267,16 @@ Flags that are marked as `stable` are tested and verified in tests and real-worl While OpenTelemetry for shell provides comprehensive automatic instrumentation, there are some technical limitations to be aware of: +### Shell Functions +By design, shell functions are not automatically instrumented. The aliasing mechanism used for auto-instrumentation only works for external commands, built-ins, and aliases, but cannot intercept function calls within the shell's execution context. + +**Workaround:** Use `otel_observe` to manually instrument function calls where observability is needed. + +### Absolute and Relative Path Commands +Commands called via absolute or relative paths (e.g., `/bin/cat` or `./mycommand`) are not automatically instrumented by default. The auto-instrumentation mechanism relies on command name resolution through the shell's normal lookup process, which bypasses aliasing for explicit paths. + +**Workaround:** Use `otel_observe` to manually instrument these commands, or enable `OTEL_SHELL_CONFIG_INSTRUMENT_ABSOLUTE_PATHS=TRUE` (experimental) to instrument them automatically. + ### Shell Functions Without the `function` Keyword Shell functions can be defined in two ways: using the `function` keyword (`function mycommand() { ... }`) or without it (`mycommand() { ... }`). When a function is defined without the `function` keyword and its name collides with an actual command on the system (e.g., defining `curl() { ... }` when `/usr/bin/curl` exists), the instrumentation system may not correctly distinguish between the function and the command. This is because the aliasing mechanism used for auto-instrumentation relies on command type detection, which can be ambiguous in these cases. @@ -277,18 +287,14 @@ The instrumentation uses file descriptor 7 as a communication channel to the Ope **Workaround:** Avoid using file descriptor 7 in your scripts. If you must use a specific file descriptor, choose a different number (e.g., 8, 9, or higher). You can also override the file descriptor used by OpenTelemetry by setting the `OTEL_REMOTE_SDK_FD` environment variable to a different number before sourcing the instrumentation. +### Restricted Mode +Shells running in restricted mode (`set -r`) are not supported. The instrumentation requires the ability to modify the shell environment, set aliases, and execute arbitrary commands, which are prohibited in restricted mode. + ### PID Tracking for Background Processes When commands are instrumented, they are wrapped in shell functions rather than being executed directly. This means that if you save the PID of a background process (using `$!`) and later try to kill it, you may end up killing the instrumentation wrapper subshell instead of the actual command. This can result in the command continuing to run even though you attempted to terminate it. **Workaround:** Instead of relying on `$!` immediately after launching a background command, use `ps` and `grep` to find the actual process by its command name and then use `kill ` with the specific numeric PID. For example: `pid=$(ps -o pid,comm | grep mycommand | grep -v grep | awk '{print $1}')` followed by `kill $pid`. Alternatively, implement proper process tracking using PID files or other inter-process communication mechanisms. -### Restricted Mode -Shells running in restricted mode (`set -r`) are not supported. The instrumentation requires the ability to modify the shell environment, set aliases, and execute arbitrary commands, which are prohibited in restricted mode. - -### Additional Known Limitations -- Shell functions (as mentioned above) are not automatically instrumented. Use `otel_observe` to manually instrument function calls. -- Commands called via absolute or relative paths (e.g., `/bin/cat` or `./mycommand`) are not automatically instrumented by default. Use `otel_observe` or enable `OTEL_SHELL_CONFIG_INSTRUMENT_ABSOLUTE_PATHS=TRUE` (experimental) to instrument these commands. - ## Traces The API described below is for manually creating and customizing spans. We recommend to do this only if the automatic instrumentation is not sufficient.