Logs#

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.

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 log level --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 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

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.

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.

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"
}

Audit Log#

Package Manager supports audit logs 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.

Audit Log Limitations

The Package Manager Audit log is a new feature and is not yet comprehensive. The audit log currently captures high-level actions that are relevant to custom package metadata.

Audit Log Properties#

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

time

A timestamp that identifies when the action was initiated.

Type: string

Appears: all logs

user

Information about the user that initiated the action. For local admin users accessing the Package Manager API via the Admin CLI on the server, the user is an object that includes the pid, uid, and gid properties to identify the calling process ID, user ID, and group ID, respectively. For remote users accessing the Package Manager API via an API token, the user is simply the GUID associated with the user's API token.

Type: varies

Appears: all logs

user_type

Identifies the type of user that initiated the action. Possible values include:

domain_socket - A local admin user accessing the Package Manager API via the Admin CLI on the server.

token - A remote user accessing the Package Manager API via an API token.

Type: string

Appears: all logs

msg

The message associated with the action. The message provides a high-level description of the audit log. Possible values include:

API audit - An action involving use of the Package Manager API.

Type: string

Appears: all logs

category

Set to one of the following

metadata - An action involving custom package metadata.

Type: string

Appears: all logs

event

Identifies the type of event associated with the action. Possible values include:

update - A new package metadata record was created or an existing record was updated.

bulk_update - A bulk create/update action was attempted. Affected and rejected records are recorded in the parameters property.

delete - A package metadata record was deleted.

Type: string

Appears: all logs

target_id

Identifies a record that was affected by the action. Actions that affect multiple records will not include this property.

Type: string

Appears: logs that affect a single record

log

A string that provides additional information about the action.

Type: string array

Appears: all logs

parameters

An object that includes details about the action. For example:

For metadata update actions, the parameters object includes the affected metadata record.

For metadata bulk_update actions, the parameters object includes the affected and rejected records.

Type: string

Appears: logs where additional information is appropriate

Audit Log Examples#

Below are examples of typical audit logs.

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",
    "category": "metadata",
    "event": "delete",
    "log": "multiple metadata records deleted.",
    "parameters": [
        55,
        56
    ]
}

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.