Logging

Server Log

Package Manager’s default server logging outputs are STDOUT and /var/log/rstudio/rstudio-pm/rstudio-pm.log. The log file is owned by rstudio-pm with permissions 0600. Because the service logs to STDOUT, the system journal also captures this output, which you can read with journalctl -u rstudio-pm. This is useful for diagnosing startup failures, which appear in the journal as well as the product log file.

If logrotate is available when Posit Package Manager is installed, a logrotate configuration will be installed. The default configuration is to rotate the log file daily. The old log file will be stored alongside the original with a numeric extension, .1, .2, etc. The rotated log files are compressed after one day. The .1 log file is retained uncompressed, but older logs are compressed. Most systems use gzip for compression, giving log files with extensions like .2.gz, .3.gz. Logs will be maintained for 30 days.

The manual for logrotate has more information.

Note

Please note that if the logging output file of Package Manager is changed, logrotate will also need to be reconfigured.

Log levels, including debug logging levels, are controlled via the Logging.SystemLogLevel variable. This section is documented in the configuration appendix.

/etc/rstudio-pm/rstudio-pm.gcfg
[Logging]
SystemLog = STDOUT,/var/log/rstudio/rstudio-pm/rstudio-pm.log
SystemLogLevel = INFO
SystemLogFormat = JSON

Additionally, the system log level can be configured via the admin CLI command rspm config log --level=[level] command.

Terminal
rspm config log --level=DEBUG

Package Service Log

Package Manager can log information about serving source and binary packages. To enable the package service log, define the Server.ServiceLog configuration property.

/etc/rstudio-pm/rstudio-pm.gcfg
[Server]
ServiceLog = "/var/log/rstudio/rstudio-pm/rstudio-pm.service.log"

The package service log file is owned by rstudio-pm with permissions 0600. The log file is stored in JSON format, with each row being a valid JSON object.

Package Manager does not rotate the package service log. Configure rotation for this log to manage its size.

Package Service Log Properties

Each row of the package service log is a valid JSON object. The following properties may be included.

time

A timestamp that identifies when the request was initiated.

Type: string

Appears: all logs

name

The name of the package that was requested.

Type: string

Appears: all logs

version

The version of the package that was requested.

Type: string

Appears: all logs

filename

The filename of the PyPI package file that was requested.

Type: string

Appears: PyPI package file requests only

sha256

The SHA-256 hash of the PyPI package file that was requested.

Type: string

Appears: PyPI package file requests only

class

Set to one of the following

  • current - A current source package request.
  • archived - An archived source package request.
  • binary_win - A Windows binary package request.
  • binary_mac - A macOS binary package request.
  • pypi_file - A PyPI package file request.
  • vsx_asset - A VSX extension (VSIX) download request.

Type: string

Appears: all logs

source

Set to the source name for the current package request. This is useful for determining which source a package originates from, particularly when a repo contains multiple sources.

Type: string

Appears: all logs

src_type

Set to the source type for the current package request. This is useful for determining which source type a package originates from.

Type: string

Appears: all logs

lic_type

An array of the SPDX license identifiers associated with the current package request. If the package license cannot be associated with a standardized license identifier in the SPDX License List, Unknown will be returned.

Type: string array

Appears: all logs

type

Indicates one of the following request types

  • source_archived - The request is for an archived package source.
  • source_current - The request is for a current package source.
  • binary_archived - The request is for an archived package binary.
  • binary_current - The request is for a current package binary.

Type: string

Appears: all logs

distro

For package binary requests, indicates the distro requested. When R is configured to use Linux binaries, the distro is the URL segment that directly follows __linux__/. On Windows, the distro indicates the R version, e.g., 3.5-win.

Type: string

Appears: binary requests only

r_version

For package binary requests, indicates the R version requested. The R version is indicated in the User-Agent header value.

Type: string

Appears: binary requests only

match_type

For package binary requests, indicates one of the following match types.

  • best - A best-matching R version was calculated based on the User-Agent header value.

Type: string

Appears: binary requests only

failed_service

The presence of this property indicates a service failure. If the log line includes a message property of ok, then a failed_service property indicates that a package binary request was unsuccessful, but the service was able to successfully fall back to serving the package source. However, if the log line’s message property includes an error message, then the request failed.

Service failure values include:

  • service_error_ash - Failure while calculating the unique signature (ASH) for a package binary.
  • service_error_fetch - Failure while fetching package binary or source files from storage.
  • service_error_blocked - Failure when attempting to download a package that is blocked through the security rules.
  • service_error_unavailable - Failure when attempting to download a PyPI package file before the security rules have loaded.

Type: string

Appears: failed and source fallback requests (service failure related)

failed_ua

For package binary requests, the presence of this property property indicates a User-Agent failure. User-Agent failures include:

  • ua_error_none - No User-Agent header was found.
  • ua_error_unsupported_os - The User-Agent header value indicates an OS that is not supported.
  • ua_error_no_r - The User-Agent header value does not indicate the R version.
  • ua_error_distro_mismatch - The OS indicated by the User-Agent header value does not match the OS for the distro.

Type: string

Appears: User-Agent-related source fallback requests

user_agent

For User-Agent failures, the User-Agent header value is included for reference.

Type: string

Appears: User-Agent-related source fallback requests

failed_match

For package binary requests, the presence of this property indicates a failure related to calculating a best-matching R version. Values include:

  • match_error_no_best_match - No matching R version was found.

Type: string

Appears: Match-related source fallback requests

error

For service failures that result in falling back to serving source, an error property may be included to indicate an error message associated with the service failure.

Type: string

Appears: source fallback requests (service failure related)

message

For requests ending in failure, the error message is indicated by the message property. All other requests, including requests for binaries that successfully fall back to source due to one of the above failure modes,will return a value of ok.

Type: string

Appears: all logs

Package Service Log Examples

Below are examples of typical package service logs.

  • Successfully serving a current package binary for a Linux distribution.

    {
        "time": 1563907529,
        "name": "plumber",
        "version": "0.4.6",
        "class": "current",
        "type": "binary_current",
        "distro": "rhel9",
        "r_version": "4.3.1",
        "match_type": "best",
        "message": "ok"
    }
  • A current package binary was requested, but was not available to download. Package Manager automatically fell back to serving the package source, which succeeded.

    {
        "time": 1563907544,
        "name": "plumber",
        "version": "0.4.6",
        "class": "current",
        "type": "binary_current",
        "distro": "rhel9",
        "r_version": "4.3.1",
        "match_type": "best",
        "error": "DownloadBinaryEtagRunner: file not found: https://rspm-sync.rstudio.com/bin/4.3-rhel9/e3f8ab6d0bd9f83cb787b4f7472d60d98f247f64ea2c8a32aff68be6abbde5cf.tar.gz",
        "failed_service": "service_error_fetch",
        "message": "ok"
    }
  • A current package binary was requested, but the R version was not supported by Package Manager. Package Manager automatically fell back to serving the package source, which succeeded.

    {
        "time": 1563907562,
        "name": "plumber",
        "version": "0.4.6",
        "class": "current",
        "type": "binary_current",
        "distro": "jammy",
        "r_version": "2.15.3",
        "failed_match": "match_error_no_best_match",
        "message": "ok"
    }
  • A current package binary was requested, but the User-Agent header did not indicate an R version. Package Manager automatically fell back to serving the package source, which succeeded. Note that the user_agent property is included in this case to aid in debugging.

    {
        "time": 1563907598,
        "name": "plumber",
        "version": "0.4.6",
        "class": "current",
        "type": "binary_current",
        "distro": "jammy",
        "failed_ua": "ua_error_no_r",
        "user_agent": "Q (3.5.3 x86_64-pc-linux-gnu x86_64 linux-gnu)",
        "message": "ok"
    }
  • A current package binary was requested, but the User-Agent header indicated an unsupported OS. Package Manager automatically fell back to serving the package source, which succeeded. Note that the user_agent property is included in this case to aid in debugging.

    {
        "time": 1564757046,
        "name": "plumber",
        "version": "0.4.6",
        "class": "current",
        "type": "binary_current",
        "distro": "xenial",
        "failed_ua": "ua_error_unsupported_os",
        "user_agent": "python-requests/2.9.1",
        "message": "ok"
    }
  • Serving a current package source.

    {
        "time": 1563907590,
        "name": "plumber",
        "version": "0.4.6",
        "class": "current",
        "type": "source_current",
        "message": "ok"
    }
  • Serving a PyPI package file.

    {
        "time": 1563907600,
        "name": "numpy",
        "version": "1.24.0",
        "filename": "numpy-1.24.0-cp311-cp311-manylinux_2_17_x86_64.whl",
        "sha256": "a12b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
        "class": "pypi_file",
        "message": "ok"
    }
  • Serving a VS Code extension (VSIX) download.

    {
        "time": 1773780095,
        "class": "vsx_asset",
        "filename": "redhat.java-1.38.0.vsix",
        "lic_type": ["EPL-2.0"],
        "name": "redhat.java",
        "source": "openvsx",
        "src_type": "Open VSX",
        "version": "1.38.0",
        "message": "ok"
    }

Audit log

Package Manager supports an audit log for tracking changes and security-relevant information. To enable the audit log, define the AuditLog.Enabled configuration property.

/etc/rstudio-pm/rstudio-pm.gcfg
[AuditLog]
Enabled = true
AuditLog = "/var/log/rstudio/rstudio-pm/rstudio-pm-audit.log"
AuditLogFormat = JSON

The audit log file is owned by rstudio-pm with permissions 0600. The log file is stored in JSON format by default, with each row being a valid JSON object.

Package Manager does not rotate the audit log. Package Manager writes a repository access entry for every request to a repository that requires authentication, so the audit log can grow quickly. If you write the audit log to a file, configure rotation to manage its size. Keep the rotated files for as long as your audit policy requires.

NoteAudit log limitations

The Package Manager audit log is not comprehensive. It records:

  • Creating and deleting repositories and sources.
  • Editing and renaming repositories.
  • Subscribing sources to repositories, unsubscribing them, and changing their order.
  • High-level actions on custom package metadata.
  • Package request changes.
  • Experimental feature changes.
  • Token creation and revocation.
  • Token email removal.
  • Test emails.
  • The outcome of each email that Package Manager sends.
  • Access to repositories that require authentication.

Package Manager records repository and source changes the same way whether they come from the Admin CLI or from the API with a token, and only when the change succeeds. The audit log does not record other configuration changes, such as editing or renaming a source.

The audit log also does not record what Package Manager creates at startup. This includes the repositories from the [Repos] settings, their source subscriptions, and the built-in cran, pypi, bioconductor, and openvsx sources.

Reading audit rows

The category and event fields identify the action in each row. For example, this row records a failed repository read check:

{
  "time": "2026-10-21T17:00:00Z",
  "level": "INFO",
  "msg": "Repository access",
  "category": "repository",
  "event": "access_denied",
  "repo": "private-cran",
  "user_type": "anonymous"
}
Category Event Meaning
metadata update Package Manager created or updated a custom package metadata record.
metadata bulk_update A bulk create or update completed. parameters includes affected and rejected records.
metadata delete Package Manager deleted custom package metadata.
repository create Package Manager created a repository.
repository delete Package Manager deleted a repository.
repository subscribe Package Manager subscribed a source to a repository.
repository unsubscribe Package Manager unsubscribed a source from a repository.
repository edit Package Manager edited or renamed a repository. The parameters property records the changed fields. The audit log does not record edits that change nothing.
repository reorder Package Manager changed the order of a repository’s sources.
repository access_granted The repository read check passed. Other checks, such as a missing admin scope, can still refuse the request.
repository access_denied The read check failed for a repository that requires authentication.
source create Package Manager created a source.
source delete Package Manager deleted a source.
package_request submit A user submitted a package request.
package_request edit A user edited the contents of a package request, or changed only its email choice.
package_request withdraw A user withdrew a package request.
package_request review A reviewer submitted decisions.
experimental enable An administrator turned on an experimental feature.
experimental disable An administrator turned off an experimental feature.
token create Package Manager created a token, for example from the Authentication Tokens page, rspm create token, or a bootstrap request.
token revoke Package Manager revoked a token, for example from the Authentication Tokens page or rspm revoke token.
token clear-email An administrator removed an email address from tokens and package requests. See Email removal fields.
mail test An administrator sent a test email. result tells you if the send worked.
mail delivery An email reached its final outcome. See Mail delivery fields.

Audit log properties

The following tables describe the fields in each row. The TEXT and STRUCTURED formats print packages, decisions, and emails as text.

Common fields

Property JSON type Present when Meaning
time string Every row Timestamp when Package Manager wrote the row.
level string Every row Log level. Audit rows use INFO.
user object or string Identified user Identity of the user who initiated the action. See User identity.
user_type string Every row Authentication type. See User identity.
user_name string User has a name Name of the user who initiated the action. See User identity.
msg string Every row API audit for actions through the Package Manager API. Repository access for repository access checks. Email delivery for email outcomes.
category string Every row Action category. See Reading audit rows for categories and events.
event string Every row Event within the category.
log string Every API audit row Additional description of the action.
repo string repository or package_request Repository changed or accessed, or target repository after a package request change.

Repository access rows contain only these fields.

Repository and source fields

Property JSON type Present when Meaning
target_id number (integer) Every repository and source change Identifier of the repository or source that changed.
repo_type string repository change Type of the repository, such as R, Python, Bioconductor, or VSX.
auth boolean repository create Whether the new repository requires authentication.
source string source change, or repository subscribe or unsubscribe Name of the source that changed, or that Package Manager subscribed or unsubscribed.
source_type string Row has source Type of the source, such as Local, Curated CRAN, or Git.
bioc_version string subscribe for a Bioconductor version Bioconductor version of the subscription.
old_sources array of strings repository reorder Order of the repository’s sources before the change, by name.
sources array of strings repository reorder New order of the repository’s sources, by name.
parameters object repository edit Old and new value of each changed field: name, description, hidden, or auth.

Metadata fields

Property JSON type Present when Meaning
target_id number (integer) update, or delete of one record Identifier of the affected metadata record. Absent for actions that affect multiple records.
parameters object update Affected metadata record.
parameters object bulk_update Affected and rejected records, with their counts.
parameters array of numbers delete of multiple specified records Identifiers supplied for deletion.

Deleting all metadata records omits both target_id and parameters.

Package request fields

EnhancedAdvanced

These rows describe package requests, an experimental feature.

Property JSON type Present when Meaning
request_id string Every package request row Unique package request identifier. The request pages in the web UI show it as Request ID.
request_status string Every package request row Status after the change: pending, approved, partially_approved (some packages approved and the rest denied), denied, or withdrawn.
request_version number (integer) Every package request row Version number after the change. It starts at 1, and each edit of the contents adds 1. Reviews, withdrawals, and changes to the email choice alone keep it.
requester string Every package request row User who submitted the request. Package Manager reads it from the stored request, so a request submitted over the local domain socket, or with an older token that has no user, shows local socket.
packages array of objects submit, or edit of the contents Complete list of requested packages after the change. An edit row that changes only the email choice omits it. See package entries.
decisions array of objects review Approved and denied packages in the submitted decisions. See decision entries.
emails array of objects submit or review Emails the change queued. The list is empty when the change queued no email. See email entries.

Each packages entry contains the following fields:

Property JSON type Present when Meaning
name string Every entry Requested package name.
version string Request names a version or a version constraint Requested version or version constraint.

Each decisions entry contains the following fields:

Property JSON type Present when Meaning
name string Every entry Package name.
decision string Every entry approve or deny.
target_source string approve Curated source chosen for the package. Absent from denied entries.

Each emails entry contains the following fields:

Property JSON type Present when Meaning
template string Every entry package-request-submitted for the email to a reviewer, or package-request-decided for the email to the requester.
key string Every entry Queue key of the email. Each email has a different key. A new decision on a request queues an email with a new key.
recipient string Every entry Email address that gets the email.

The row records that Package Manager queued the email. A mail delivery row records the outcome.

Experimental feature fields

Property JSON type Present when Meaning
feature string Every experimental row Key of the experimental feature.

Token fields

Token rows never include the token value. The user identity fields name who created or revoked the token, or removed an email address. subject names who the token is for. A bootstrap token’s row has the bootstrap user type.

Property JSON type Present when Meaning
token_guid string create, revoke, or clear-email with --guid Globally unique identifier (GUID) of the token.
scopes array of strings create, revoke, or clear-email with --guid Scopes of the token, such as repos:read. The row omits source and repository lists.
subject string create, revoke, or clear-email with --guid Who the token is for, such as the --user value from rspm create token, or bootstrap for a bootstrap token.
description string create, revoke, or clear-email with --guid Description of the token.
expires string create, revoke, or clear-email with --guid Time the token expires, or never.

Email removal fields

EnhancedAdvanced

Package Manager writes a clear-email row when an administrator runs rspm edit token --clear-email. See Changing a token’s email.

Property JSON type Present when Meaning
cleared_tokens number (integer) Every clear-email row Number of tokens that lost the address, revoked tokens included.
cleared_requests number (integer) Every clear-email row Number of package requests that lost the address.
cleared_request_versions number (integer) Every clear-email row Number of package request versions that lost the address.
cleared_request_audit_entries number (integer) Every clear-email row Number of package request activity entries that lost the address.

The row has no field for the removed address. A removal with --guid also has the token fields, and its subject can be the removed address. A removal by address has no token fields.

Mail fields

Property JSON type Present when Meaning
result string Every test row success when the mail server accepted the message, or the file provider wrote it. failure when Mail.Provider is none or the send failed.
recipient string Every test row Address the test email went to.
provider string Every test row Value of Mail.Provider.
host string Every test row Value of SMTP.Host. Only the smtp provider uses it.
port number (integer) Every test row Value of SMTP.Port. Only the smtp provider uses it.

Mail delivery fields

EnhancedAdvanced

Package Manager writes a delivery row when an email reaches its final outcome. Retries after a failed send add no rows. If Package Manager delivers the same email twice, it writes a second sent row.

Property JSON type Present when Meaning
result string Every delivery row sent, failed, expired, or discarded. sent means that the mail server accepted the email, or the file provider wrote it. It does not confirm delivery to the inbox.
template string Every delivery row Email template, such as package-request-submitted or package-request-decided.
key string Every delivery row Queue key of the email. It matches key in an emails entry of the submit or review row.
send_id string The email has a send identifier For a package request email notification, the request_id of the request.
recipients array of strings Every delivery row Intended recipients of the email. A failed or discarded email also lists them.
attempts number (integer) Every delivery row Number of sends that Package Manager tried.
error string The send returned an error, or the email expired First line of the error, up to 500 bytes.
{
  "time": "2026-10-21T17:01:03.102938475Z",
  "level": "INFO",
  "msg": "Email delivery",
  "user_type": "system",
  "user_name": "email-sender",
  "category": "mail",
  "event": "delivery",
  "log": "sent email",
  "result": "sent",
  "template": "package-request-decided",
  "key": "package-request-decided-356a8674-f5bb-4b86-b749-a883557fe421-0",
  "send_id": "356a8674-f5bb-4b86-b749-a883557fe421",
  "recipients": ["requester@example.com"],
  "attempts": 1
}

A discarded row has one of two causes:

user_name log Cause
email-sender discarded email: Mail.Provider is none Mail.Provider is none.
The user who withdrew or decided the request discarded email: the package request was closed before it was sent The request closed before Package Manager sent its submission email notification.

To alert on a disabled mail provider, match user_name=email-sender and result=discarded. The email-sweeper user writes the expired rows.

A second decision on the same request queues an email notification with the same send_id. To match a delivery row to its review row, use key.

User identity

User type user JSON type user value user_name value
domain_socket object Local Admin CLI user. Numeric pid, uid, and gid identify the calling process, user, and group. No user_name field.
token string Remote API user. Globally unique identifier (GUID) of the user’s API token. User the token belongs to: the --user value from rspm create token, or the signed-in user for tokens from rspm login. Older tokens created without a user have no user_name field.
session_cookie string User signed in to the web UI. Token identifier from the sign-in session. Username of the signed-in user.
anonymous No user field Request without credentials. No user_name field.
bootstrap No user field Bootstrap request, authenticated by a signature that matches Bootstrap.PublicKey instead of a user. No user_name field.
system No user field Work that Package Manager does on its own, such as sending email. Name of the task, such as email-sender or email-sweeper.

Audit log examples

Below are examples of typical rows in the audit log.

  • Subscribing a source to a repository with the Admin CLI

    {
      "time": "2026-10-20T09:31:02.51837Z",
      "level": "INFO",
      "msg": "API audit",
      "user": {
        "pid": 2210,
        "uid": 0,
        "gid": 0
      },
      "user_type": "domain_socket",
      "category": "repository",
      "event": "subscribe",
      "log": "subscribed source to repository",
      "target_id": 3,
      "repo": "prod-cran",
      "repo_type": "R",
      "source": "internal",
      "source_type": "Local"
    }
  • Successfully creating custom metadata for a package

    {
      "time": "2024-11-22T12:14:24.241629106Z",
      "level": "INFO",
      "msg": "API audit",
      "user": {
        "pid": 1629,
        "uid": 1000,
        "gid": 1001
      },
      "user_type": "domain_socket",
      "category": "metadata",
      "event": "update",
      "log": "created/updated metadata record",
      "target_id": 58,
      "parameters": {
        "id": 58,
        "package_name": "tidyverse",
        "key": "Recommended",
        "value": "true",
        "constraints": [
          {
            "repo_id": 3
          }
        ]
      }
    }
  • Successfully deleting two metadata records

    {
        "time": "2024-11-22T12:14:46.21887263Z",
        "level": "INFO",
        "msg": "API audit",
        "user": "7dbf6dfd-879f-4cb1-ba2a-5aa70075c577",
        "user_type": "token",
        "user_name": "demo-admin",
        "category": "metadata",
        "event": "delete",
        "log": "multiple metadata records deleted.",
        "parameters": [
            55,
            56
        ]
    }
  • Submitting a package request

    {
      "time": "2026-10-21T17:00:52.363397031Z",
      "level": "INFO",
      "msg": "API audit",
      "user": "0bd2df84-c38f-4909-9503-b925ce2e76a7",
      "user_type": "token",
      "user_name": "demo-requester",
      "category": "package_request",
      "event": "submit",
      "log": "submitted package request",
      "request_id": "356a8674-f5bb-4b86-b749-a883557fe421",
      "repo": "audit-demo-r",
      "request_status": "pending",
      "request_version": 1,
      "requester": "demo-requester",
      "packages": [
        {
          "name": "cli"
        },
        {
          "name": "glue"
        }
      ],
      "emails": [
        {
          "template": "package-request-submitted",
          "key": "package-request-submitted-356a8674-f5bb-4b86-b749-a883557fe421-0",
          "recipient": "reviewer@example.com"
        }
      ]
    }
  • Completing a review, after one edit, that approves one package and denies another

    {
      "time": "2026-10-21T17:00:56.471493497Z",
      "level": "INFO",
      "msg": "API audit",
      "user": "923f9ea0-0ea1-4064-8c3d-b08fe38088b0",
      "user_type": "token",
      "user_name": "demo-reviewer",
      "category": "package_request",
      "event": "review",
      "log": "saved package request review",
      "request_id": "356a8674-f5bb-4b86-b749-a883557fe421",
      "repo": "audit-demo-r",
      "request_status": "partially_approved",
      "request_version": 2,
      "requester": "demo-requester",
      "decisions": [
        {
          "name": "cli",
          "decision": "approve",
          "target_source": "audit-demo-curated"
        },
        {
          "name": "glue",
          "decision": "deny"
        }
      ],
      "emails": [
        {
          "template": "package-request-decided",
          "key": "package-request-decided-356a8674-f5bb-4b86-b749-a883557fe421-0",
          "recipient": "requester@example.com"
        }
      ]
    }

Access Logs

The Package Manager HTTP access logs are located at /var/log/rstudio/rstudio-pm/rstudio-pm.access.log. This file is owned by rstudio-pm with permissions 0600. Log files are stored in Apache Combined Log Format.

You can switch to the Apache Common Log Format if preferred by setting Server.AccessLogFormat = "common".

When Package Manager is installed, if available, the logrotate configuration is also installed. The default configuration is to rotate the log file daily. The old log file will be compressed and stored alongside the original log file with a .1.gz extension (then .2.gz, etc.). Logs will maintained for 30 days.

Note

For information on the differences between the Apache Combined Log Format and the Apache Common Log Format refer to Apache’s documentation here.

Back to top