{"id":15057013,"url":"https://github.com/parca-dev/parca-agent","last_synced_at":"2025-05-15T00:12:14.430Z","repository":{"id":36964847,"uuid":"364992209","full_name":"parca-dev/parca-agent","owner":"parca-dev","description":"eBPF based always-on profiler auto-discovering targets in Kubernetes and systemd, zero code changes or restarts needed!","archived":false,"fork":false,"pushed_at":"2024-10-24T13:10:03.000Z","size":67260,"stargazers_count":546,"open_issues_count":154,"forks_count":67,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-10-29T22:32:39.748Z","etag":null,"topics":["bpf","c","continuous-profiling","cpp","ebpf","ebpf-programs","go","golang","hacktoberfest","kubernetes","libbpf","linux","observability","performance","pprof","profiling","python","ruby","rust","systemd"],"latest_commit_sha":null,"homepage":"https://parca.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parca-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-06T17:46:43.000Z","updated_at":"2024-10-29T04:56:25.000Z","dependencies_parsed_at":"2023-10-14T20:10:51.308Z","dependency_job_id":"2e59728c-2e48-4526-afa5-f950ad4ed3fd","html_url":"https://github.com/parca-dev/parca-agent","commit_stats":{"total_commits":2842,"total_committers":45,"mean_commits":63.15555555555556,"dds":0.5439831104855735,"last_synced_commit":"2e00ac03054f6cd722f42ce564ec66c0b8bf7ef8"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parca-dev%2Fparca-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parca-dev%2Fparca-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parca-dev%2Fparca-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parca-dev%2Fparca-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parca-dev","download_url":"https://codeload.github.com/parca-dev/parca-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247517905,"owners_count":20951718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","c","continuous-profiling","cpp","ebpf","ebpf-programs","go","golang","hacktoberfest","kubernetes","libbpf","linux","observability","performance","pprof","profiling","python","ruby","rust","systemd"],"created_at":"2024-09-24T22:00:30.048Z","updated_at":"2025-04-06T17:08:40.284Z","avatar_url":"https://github.com/parca-dev.png","language":"Go","readme":"[![Apache 2 License](https://img.shields.io/badge/license-Apache%202-blue.svg)](LICENSE)\n![Build](https://github.com/parca-dev/parca-agent/actions/workflows/build.yml/badge.svg)\n![Container](https://github.com/parca-dev/parca-agent/actions/workflows/container.yml/badge.svg)\n[![parca-agent](https://snapcraft.io/parca-agent/badge.svg)](https://snapcraft.io/parca-agent)\n\n# Parca Agent\n\nParca Agent is an always-on sampling profiler that uses eBPF to capture raw profiling data with very low overhead. It observes user-space and kernel-space stacktraces [19 times per second](https://www.parca.dev/docs/parca-agent-design#cpu-sampling-frequency) and builds [pprof](https://github.com/google/pprof) formatted profiles from the extracted data. Read more details in the [design documentation](https://www.parca.dev/docs/parca-agent-design).\n\nThe collected data can be viewed locally via HTTP endpoints and then be configured to be sent to a [Parca](https://github.com/parca-dev/parca) server to be queried and analyzed over time.\n\n## Requirements\n\n- Linux Kernel version 5.3+ with BTF\n\n## Quickstart\n\nSee the [Kubernetes Getting Started](https://www.parca.dev/docs/kubernetes).\n\n## Language Support\n\nParca Agent is continuously enhancing its support for multiple languages.\nIncomplete list of languages we currently support:\n\n- C, C++, Go (with extended support), Rust\n- .NET, Deno, Erlang, Java, Julia, Node.js, Wasmtime, PHP 8 and above\n- Ruby, Python\n\nPlease check [our docs](https://www.parca.dev/docs/parca-agent-language-support) for further information.\n\n\u003e [!NOTE]\n\u003e [Further language support](https://github.com/parca-dev/parca-agent/issues?q=is%3Aissue+is%3Aopen+label%3Afeature%2Flanguage-support) is coming in the upcoming weeks and months.\n\n## Supported Profiles\n\nTypes of profiles that are available:\n\n- On-CPU\n- Soon: Network usage, Allocations\n\n\u003e [!NOTE]\n\u003e Please check [our docs](https://www.parca.dev/docs/parca-agent-language-support) if your language is supported.\n\nThe following types of profiles require explicit instrumentation:\n\n- Runtime specific information such as Goroutines\n\n## Debugging\n\n### Logging\n\nTo debug potential errors, enable debug logging using `--log-level=debug`.\n\n## Configuration\n\n\u003cdetails\u003e\u003csummary\u003eFlags:\u003c/summary\u003e\n\u003cp\u003e\n\n[embedmd]:# (dist/help.txt)\n```txt\nUsage: parca-agent\n\nFlags:\n  -h, --help                       Show context-sensitive help.\n      --log-level=\"info\"           Log level.\n      --log-format=\"logfmt\"        Configure if structured logging as JSON or as\n                                   logfmt\n      --http-address=\"127.0.0.1:7071\"\n                                   Address to bind HTTP server to.\n      --version                    Show application version.\n      --node=\"hostname\"           The name of the node that the process is\n                                   running on. If on Kubernetes, this must match\n                                   the Kubernetes node name.\n      --config-path=\"\"             Path to config file.\n      --memlock-rlimit=0           The value for the maximum number of bytes\n                                   of memory that may be locked into RAM. It is\n                                   used to ensure the agent can lock memory for\n                                   eBPF maps. 0 means no limit.\n      --mutex-profile-fraction=0\n                                   Fraction of mutex profile samples to collect.\n      --block-profile-rate=0       Sample rate for block profile.\n      --profiling-duration=10s     The agent profiling duration to use. Leave\n                                   this empty to use the defaults.\n      --profiling-cpu-sampling-frequency=19\n                                   The frequency at which profiling data is\n                                   collected, e.g., 19 samples per second.\n      --profiling-perf-event-buffer-poll-interval=250ms\n                                   The interval at which the perf event buffer\n                                   is polled for new events.\n      --profiling-perf-event-buffer-processing-interval=100ms\n                                   The interval at which the perf event buffer\n                                   is processed.\n      --profiling-perf-event-buffer-worker-count=4\n                                   The number of workers that process the perf\n                                   event buffer.\n      --metadata-external-labels=KEY=VALUE;...\n                                   Label(s) to attach to all profiles.\n      --metadata-container-runtime-socket-path=STRING\n                                   The filesystem path to the container runtimes\n                                   socket. Leave this empty to use the defaults.\n      --metadata-disable-caching\n                                   Disable caching of metadata.\n      --local-store-directory=STRING\n                                   The local directory to store the profiling\n                                   data.\n      --remote-store-address=STRING\n                                   gRPC address to send profiles and symbols to.\n      --remote-store-bearer-token=STRING\n                                   Bearer token to authenticate with store\n                                   ($PARCA_BEARER_TOKEN).\n      --remote-store-bearer-token-file=STRING\n                                   File to read bearer token from to\n                                   authenticate with store.\n      --remote-store-insecure      Send gRPC requests via plaintext instead of\n                                   TLS.\n      --remote-store-insecure-skip-verify\n                                   Skip TLS certificate verification.\n      --remote-store-batch-write-interval=10s\n                                   Interval between batch remote client writes.\n                                   Leave this empty to use the default value of\n                                   10s.\n      --remote-store-rpc-logging-enable\n                                   Enable gRPC logging.\n      --remote-store-rpc-unary-timeout=5m\n                                   Maximum timeout window for unary gRPC\n                                   requests including retries.\n      --debuginfo-directories=/usr/lib/debug,...\n                                   Ordered list of local directories to search\n                                   for debuginfo files.\n      --debuginfo-temp-dir=\"/tmp\"\n                                   The local directory path to store the interim\n                                   debuginfo files.\n      --debuginfo-strip            Only upload information needed for\n                                   symbolization. If false the exact binary the\n                                   agent sees will be uploaded unmodified.\n      --debuginfo-compress         Compress debuginfo files' DWARF sections\n                                   before uploading.\n      --debuginfo-upload-disable\n                                   Disable debuginfo collection and upload.\n      --debuginfo-upload-max-parallel=25\n                                   The maximum number of debuginfo upload\n                                   requests to make in parallel.\n      --debuginfo-upload-timeout-duration=2m\n                                   The timeout duration to cancel upload\n                                   requests.\n      --debuginfo-upload-cache-duration=5m\n                                   The duration to cache debuginfo upload\n                                   responses for.\n      --debuginfo-disable-caching\n                                   Disable caching of debuginfo.\n      --symbolizer-jit-disable     Disable JIT symbolization.\n      --otlp-address=STRING        The endpoint to send OTLP traces to.\n      --otlp-exporter=\"grpc\"       The OTLP exporter to use.\n      --object-file-pool-eviction-policy=\"lru\"\n                                   The eviction policy to use for the object\n                                   file pool.\n      --object-file-pool-size=100\n                                   The maximum number of object files to keep in\n                                   the pool. This is used to avoid re-reading\n                                   object files from disk. It keeps FDs open,\n                                   so it should be kept in sync with ulimits.\n                                   0 means no limit.\n      --dwarf-unwinding-disable    Do not unwind using .eh_frame information.\n      --dwarf-unwinding-mixed      Unwind using .eh_frame information and frame\n                                   pointers.\n      --python-unwinding-disable\n                                   Disable Python unwinder.\n      --ruby-unwinding-disable     Disable Ruby unwinder.\n      --analytics-opt-out          Opt out of sending anonymous usage\n                                   statistics.\n      --telemetry-disable-panic-reporting\n\n      --telemetry-stderr-buffer-size-kb=4096\n\n      --bpf-verbose-logging        Enable verbose BPF logging.\n      --bpf-events-buffer-size=8192\n                                   Size in pages of the events buffer.\n      --verbose-bpf-logging        [deprecated] Use --bpf-verbose-logging.\n                                   Enable verbose BPF logging.\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n## Metadata Labels\n\nParca Agent supports [Prometheus relabeling](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config). The following labels are always attached to profiles:\n\n* `node`: The name of the node that the process is running on as specified by the `--node` flag.\n* `comm`: The command name of the process being profiled.\n\nAnd optionally you can attach additional labels using the `--metadata-external-labels` flag.\n\nUsing relabeling the following labels can be attached to profiles:\n\n* `__meta_process_pid`: The process ID of the process being profiled.\n* `__meta_process_cmdline`: The command line arguments of the process being profiled.\n* `__meta_process_cgroup`: The (main) cgroup of the process being profiled.\n* `__meta_process_ppid`: The parent process ID of the process being profiled.\n* `__meta_process_executable_file_id`: The file ID (a hash) of the executable of the process being profiled.\n* `__meta_process_executable_name`: The basename of the executable of the process being profiled.\n* `__meta_process_executable_build_id`: The build ID of the executable of the process being profiled.\n* `__meta_process_executable_compiler`: The compiler used to build the executable of the process being profiled.\n* `__meta_process_executable_static`: Whether the executable of the process being profiled is statically linked.\n* `__meta_process_executable_stripped`: Whether the executable of the process being profiled is stripped from debuginfo.\n* `__meta_system_kernel_release`: The kernel release of the system.\n* `__meta_system_kernel_machine`: The kernel machine of the system (typically the architecture).\n* `__meta_thread_comm`: The command name of the thread being profiled.\n* `__meta_thread_id`: The PID of the thread being profiled.\n* `__meta_agent_revision`: The revision of the agent.\n* `__meta_kubernetes_namespace`: The namespace of the pod the process is running in.\n* `__meta_kubernetes_pod_name`: The name of the pod the process is running in.\n* `__meta_kubernetes_pod_label_*`: The value of the label `*` of the pod the process is running in.\n* `__meta_kubernetes_pod_labelpresent_*`: Whether the label `*` of the pod the process is running in is present.\n* `__meta_kubernetes_pod_annotation_*`: The value of the annotation `*` of the pod the process is running in.\n* `__meta_kubernetes_pod_annotationpresent_*`: Whether the annotation `*` of the pod the process is running in is present.\n* `__meta_kubernetes_pod_ip`: The IP of the pod the process is running in.\n* `__meta_kubernetes_pod_container_name`: The name of the container the process is running in.\n* `__meta_kubernetes_pod_container_id`: The ID of the container the process is running in.\n* `__meta_kubernetes_pod_container_image`: The image of the container the process is running in.\n* `__meta_kubernetes_pod_container_init`: Whether the container the process is running in is an init container.\n* `__meta_kubernetes_pod_ready`: Whether the pod the process is running in is ready.\n* `__meta_kubernetes_pod_phase`: The phase of the pod the process is running in.\n* `__meta_kubernetes_node_name`: The name of the node the process is running on.\n* `__meta_kubernetes_pod_host_ip`: The host IP of the pod the process is running in.\n* `__meta_kubernetes_pod_uid`: The UID of the pod the process is running in.\n* `__meta_kubernetes_pod_controller_kind`: The kind of the controller of the pod the process is running in.\n* `__meta_kubernetes_pod_controller_name`: The name of the controller of the pod the process is running in.\n* `__meta_kubernetes_node_label_*`: The value of the label `*` of the node the process is running on.\n* `__meta_kubernetes_node_labelpresent_*`: Whether the label `*` of the node the process is running on is present.\n* `__meta_kubernetes_node_annotation_*`: The value of the annotation `*` of the node the process is running on.\n* `__meta_kubernetes_node_annotationpresent_*`: Whether the annotation `*` of the node the process is running on is present.\n* `__meta_docker_container_id`: The ID of the container the process is running in.\n* `__meta_docker_container_name`: The name of the container the process is running in.\n* `__meta_docker_build_kit_container_id`: The ID of the container the process is running in.\n* `__meta_containerd_container_id`: The ID of the container the process is running in.\n* `__meta_containerd_container_name`: The name of the container the process is running in.\n* `__meta_containerd_pod_name`: The name of the pod the process is running in.\n* `__meta_lxc_container_id`: The ID of the container the process is running in.\n* `__meta_cpu`: The CPU the sample was taken on.\n\n## Security\n\nParca Agent is required to be running as `root` user (or `CAP_SYS_ADMIN`). Various security precautions have been taken to protect users running Parca Agent. See details in [Security Considerations](https://www.parca.dev/docs/parca-agent-security).\n\nTo report a security vulnerability, see [this guide](https://www.parca.dev/docs/parca-agent-security#report-security-vulnerabilities).\n\n## Contributing\n\nCheck out our [Contributing Guide](CONTRIBUTING.md) to get started!\n\n## License\n\nUser-space code: Apache 2\n\nKernel-space code (eBPF profilers): GNU General Public License, version 2\n\n## Credits\n\nThanks to:\n\n- Kinvolk for creating [Inspektor Gadget](https://github.com/kinvolk/inspektor-gadget); some parts of this project were inspired by parts of it.\n","funding_links":[],"categories":["Projects Related to eBPF","eBPF 相关项目","Go","Continuous Profiling"],"sub_categories":["Observability","可观测性"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparca-dev%2Fparca-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparca-dev%2Fparca-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparca-dev%2Fparca-agent/lists"}