Using the latest JFrog products?
JFrog Platform User Guide
JFrog Xray 2.x Documentation
To get the latest version, go to the JFrog Unified Platform
Overview
Xray provides different facilities that allow you to maintain and monitor your installation.
System Status
Xray displays your general system status as an icon in the top ribbon. Clicking the icon provides status details.
Page contents
The overall status is an accumulation of the status for a variety of parameters. The table below describes the parameters monitored and the condition that generates a notification. Note that some notifications may be categorized as "warnings" or "errors" depending on the severity of the condition:
| Parameter | Condition for notification |
|---|---|
Connection to the PostgreSQL database | No connection |
Connection to MongoDB database | No connection |
Connection to RabbitMQ messaging service | No connection |
Connection to Global Database Server | No connection |
| Connection to Artifactory instances | No connection |
| Connection to integrated services (e.g. Whitesource) | No connection |
| Service restarts | Warning: 3 in the last 5 hours Error: 50 in the last 5 hours |
| Average CPU usage | Warning: 90% Error: 95% |
| Average RAM usage | Warning: 90% Error: 95% |
| System open files usage | Warning: 80% of maximum Error: 95% of maximum |
| Working directory disk usage | Warning: 80% of total Error: 95% of total |
| Xray data folder disk usage | Warning: 80% of maximum specified in the Xray configuration files Error: 95% of maximum specified in the Xray configuration files |
| Failed Messages Count | Warning: More than 0 failure messages Error: More than 100 failure messages |
System Logs
Features Under Construction - Coming Soon!
We are currently developing a new representation for JFrog logs in the UI. JFrog logs will still accessible via the REST API. Xray logs unlike Artifactory will not be available in the UI in the Xray 3.0 release but will be added soon.
You can view Xray's system logs from the Admin module under System Logs.
Microservice Filter | Click on any of the microservices listed to enable or disable logging from that microservice. For each microservice you can set the log level to one of ERROR, WARN, INFO, DEBUG or FINE. |
Auto Refresh | When enabled, the display will automatically refresh itself as new log entries are added. |
Auto Scroll | When enabled, the display will automatically scroll as new log entries are added. |
Download Log | Click to download a hard copy of the log file in its current state. |
Clear Log | Click to clear the display. This does not remove any entries from the actual log file. |
System Messages
Xray administrators can view a list of all artifact and data failure messages in the System Messages page, under the Admin module. Each failure can be traced to the exact step in the scanning and impact analysis Xray process in which it failed, allowing administrators to fix the issue and retry the step. Or contact JFrog support for further investigation.
Search for specific failures using the "Filter by Subject" box and by selecting the specific scan and impact steps.
Subject | The name of the failed artifact being scanned by Xray, or the data update in case of an impact analysis, such as vulnerability and licence name. |
Source | The location of the artifact being scanned by Xray (including the instance name, repo name and path within the repo), or the source of the data update in case of impact analysis (including the database sync or custom issue assigned). |
Step | The step in which the artifact failed (including the process and step name). |
Timestamp | The time in which the failure occurred. By default, the grid will be sorted from newest failure to oldest. |
Error | The detailed error message describing what caused this failure. |
Scanning
Every time a new artifact or build is added to a connected Artifactory instance, Xray scans it and its dependencies for known vulnerabilities and compliance violations and generate Issues accordingly. This process is called "Scanning". That includes the following process steps:
- Event
- Index
- Persist
- Analysis
- Alert
- Notify
- Artifactory Update
Impact Analysis
Every time new component metadata is available (vulnerabilities, licenses, etc.), Xray looks up the component in the components graph and if the update matches any watches, Xray will generate an issue and create a map of its impact to determine which artifacts are ultimately affected by it. This process is called "Impact Analysis". That includes the following process steps:
- Analysis
- Alert
- Notify
- Artifactory Update
Export and Import Configuration Settings
You can export Xray user-defined configurations to be imported to other Xray instances using a set of dedicated REST APIs. This is mainly useful when duplicating settings across multiple environments (Dev, Testing, Staging, and Production) or when moving to a single Xray to Artifactory instance ratio. The following settings include policies, watches, Ignore Rules, custom licenses, custom issues, webhooks, mail server, proxy configurations, and indexed resource settings.
REST API
Xray REST API provides the following endpoints you can use to work for exporting and importing Xray configuration settings.
Export Xray Settings | Exports configuration settings to zip file under the following path: <XRAY_HOME>/backup/config/<SERVICE_ID>_xray_exported_config_<TIMESTAMP>.zip. |
Import Xray Settings | Imports configurations settings from the exported zip file. |
Backup and Restore
JFrog Xray is made up of several " Go" services as well as some external services. Each needs to be handled separately.
Xray’s backup and restore solution is based on storage snapshotting to store data and configuration. In order to ensure data consistency and reliability, all Xray services must flush their data to disk before running the snapshot tool or keep a transaction log.
Backup Directories
The directories that should be backed up depend on whether you are running Xray in a Docker container or not.
Docker Backup Directories
To back up Xray running in a Docker container, you need to back up the $XRAY_MOUNT_ROOT directory which contains the following sub-directories:
xray
postgres
rabbitmq
- mongodb
For example, if $XRAY_MOUNT_ROOT=/root/.jfrog/xray, you would need to back up the following directories:
- /root/.jfrog/xray/xray
- /root/.jfrog/xray/postgres
- /root/.jfrog/xray/rabbitmq
- /root/.jfrog/xray/mongodb
Non-Docker Backup Directories
For non-Docker distributions, Xray's data is distributed among the following directories:
XRay Go services | /var/opt/jfrog/xray/data |
PostgreSQL | /var/opt/jfrog/postgres/data |
RabbitMQ | For a list of default Linux directories, please refer to the RabbitMQ documentation. The directories relevant for Xray are:
|
MongoDB | The default MongoDB data directory for the Linux distribution (see MongoDB documentation):
|
Running a Backup
To run a backup, simply create a snapshot of each of the backup directories described in the previous section.
Restoring from a Backup
Before restoring from a snapshot, we recommend backing up your current state.
To restore Xray from a backup:
- Stop Xray
Overwrite the data in the backup directories with the corresponding data in your backup
Start Xray
Getting Support
JFrog provides SLA based support for Pro and Enterprise licensing tiers. If you have purchased one of these tiers you may contact JFrog support through the JFrog Support Portal. In most cases, JFrog support will require some initial information about your system and relevant log files. In order to expedite handling of your issue, Xray lets you generate all the initially required information in the Admin module Support Zone screen. When opening a support ticket, you can attach the information bundle to expedite handling of your issue.
Requesting Support
To request support, create an information bundle with the relevant information, and login to JFrog Support Portal to open a support ticket and attach the information bundle.
What should I include?
We recommend including all the items in the uploaded information bundle unless you are sure about the information JFrog support will need in order to address your issue.
Collecting an Information Bundle
The support zone provides a variety of options to select what information is included in the bundle you provide JFrog support.
System info | Provides information about your system including storage, system properties, JVM information and plugin status. |
Artifactory Instances configuration | Provides information about your Artifactory instance settings. |
Configuration files | Provides configuration files that affect Xray functionality. |
Message queues | Provides information about message queues in Xray. |
Database Sync Information | Provides information on the database sync status. |
System logs | If checked, system logs are included in the information bundle. You may specify the time span for which system logs should be included. Date range Date range considers files according to the time stamp present in the file name, not by its contents. |
Thread dump | Xray will create a thread dump for all running threads. By default a single thread dump is created, however, to get a picture of how data may change over time, you can request several thread dumps separated by a specified time interval with the Number of Thread Dumps and Interval fields. |
Once you have checked all the information items you wish to include in your information bundle, click "Create" to create the bundle.
Xray HA
When creating an information bundle for an Xray HA installation, the bundle is created by the specific HA node that happens to handle the "Create" request.
Resource intensive operations
Note that creating a Thread dump and System logs may be resource intensive operations and may create large information bundles.
Previously Created Bundles
Every information bundle is displayed in the Previously Created Bundles list. The bundle can be downloaded if it was created using Artifactory 6.8 and higher that included support for Information Bundle repositories.
Overview
Content Tools