Overview

The Private Distribution Network (PDN) provides a convenient and up-to-date self-descriptive API that can be used by various tools/frameworks to automate the creation of REST calls.

Usage

PDN REST API endpoints can be invoked in any of the standard ways to invoke a RESTful API. This section describes how to use the PDN REST API using cURL as an example.

You can download cURL here. Learn how to use and configure cURL here.

Base URL

The Platform REST URL is constructed of: 

<JFrog URL>/<Service Context>/api/<API-Version>

In this document, you will find the relevant PDN Server and PDN Nodes REST APIs as well as the Open Metrics related to PDN.


PDN APIs


PDN Node APIs

Generic Download

Description: Downloads a file by the specified path from PDN.
Since: 1.0.1
Security: Artifactory credentials, with read permissions on the path
Usage: GET /artifactory/example-repo-local/example-directory/example-file.zip

curl -u admin:password -X GET http://{pdn-node-host}:8089/artifactory/example-repo-local/example-directory/example-file.zip -o ./example-file.zip

Response status codes:
200 - Successful download of the file
404 - The file does not exist on the Artifactory connected to the PDN

Ping

Description: Tests the connection with the PDN Node.
Since: 1.0.1
Security: No authentication is required
Usage: GET /api/v1/ping

curl -X GET http://{pdn-node-host}:8089/api/v1/ping

Response status codes:
200 - The node is available
5xx - The node is unavailable


PDN Server APIs

The following REST APIs are used for the PDN Server.


Ping

Description: Tests the connection with the PDN Server.
Since: 1.0.1
Security: No authentication is required
Usage: GET /api/v1/system/ping

$ curl -X GET "http://{pdn-server-host}:8082/pdnServer/api/v1/system/ping"

Response status codes:
200 - The server is available
404, 5xx
- The server is unavailable

Liveness

Description: Tests the PDN Server's liveness.
Since: 1.0.1
Security: No authentication is required
Usage: GET /api/v1/system/liveness

curl -X GET "http://{pdn-server-host}:8082/pdnServer/api/v1/system/liveness"

Response status codes:
200 - The server is alive
404, 5xx - The server is not alive

Readiness

Description: Tests the PDN Server's readiness.
Since: 1.0.1
Security: No authentication is required
Usage: GET /api/v1/system/readiness

curl -X GET "http://{pdn-server-host}:8082/pdnServer/api/v1/system/readiness"

Response status codes:
200 - The server is ready to accept traffic
404, 5xx - The server is not ready to accept traffic 

Clear Cache

Description: Cleans files from all the PDN Servers and PDN Nodes cache by NodeID, GroupId - without a status.
Since: 1.1.3
Security: No authentication is required
Usage: GET /api/v1/file/cache/:filepath with 2 query params group and node


PDN Metrics

PDN supports Open Metrics, a Cloud Native Computing Foundation sandbox project.

An admin user can create a scoped access token using system:metrics:r and use that token as the credentials for getting the service metrics. The admin can create a read-only access token to get metrics, which then enables anyone with the read-only token to read metrics. To learn more, see Access Token Structure.

Enabling PDN Open Metrics

To enable metrics for the PDN Server, make the following configuration changes to the PDN Server system.yaml.

pdnServer:
  metrics:
    enabled: true
    interval: 5
    exclude:
      - prefix_1
      - prefix_2

Next, to enable metrics in the PDN Node, make the following configuration changes to the PDN Node system.yaml.

pdnNode:
  metrics:
    enabled: true
    interval: 5
    exclude:
      - prefix_1
      - prefix_2
    basicAuthUsername: <username>
    basicAuthPassword: <password>

Metrics Log Files

The following are the two metric log files created for PDN:

  • PDN Server: $JF_PRODUCT_HOME/var/log/tracker-metrics.log
  • PDN Node: $JF_PRODUCT_HOME/var/log/distribution-node-metrics.log

PDN Server Metrics

Description: Gets the metrics for the PDN Server.
Since: 1.0.1
Security: Requires a valid Scoped Token, which contains the Scope “system:metrics:r”.
Usage: GET /api/v1/metrics
Authorization: N/A
Content-Type: application/x-www-form-urlencoded

Example:

# HELP app_disk_used_bytes Used bytes for app home directory disk device
# TYPE app_disk_used_bytes gauge
app_disk_used_bytes 5.3034051584e+11 1648462713907
# HELP app_disk_free_bytes Free bytes for app home directory disk device
# TYPE app_disk_free_bytes gauge
app_disk_free_bytes 4.69900447744e+11 1648462713907
# HELP app_io_counters_error Error
app_io_counters_error{error="not implemented yet"} 0 1648462713907
# HELP app_self_metrics_calc_seconds Total time to collect all metrics
# TYPE app_self_metrics_calc_seconds gauge
app_self_metrics_calc_seconds 0.004598048 1648462713907
# HELP app_self_metrics_total Count of collected metrics
# TYPE app_self_metrics_total gauge
app_self_metrics_total 31 1648462713907
# HELP go_memstats_heap_in_use_bytes Process go heap bytes in use
# TYPE go_memstats_heap_in_use_bytes gauge
go_memstats_heap_in_use_bytes 7.036928e+06 1648462713907
# HELP go_memstats_heap_allocated_bytes Process go heap allocated bytes
# TYPE go_memstats_heap_allocated_bytes gauge
go_memstats_heap_allocated_bytes 4.38732e+06 1648462713907
# HELP go_memstats_heap_idle_bytes Process go heap idle bytes
# TYPE go_memstats_heap_idle_bytes gauge
go_memstats_heap_idle_bytes 8.56064e+06 1648462713907
# HELP go_memstats_heap_objects_total Process go heap number of objects
# TYPE go_memstats_heap_objects_total gauge
go_memstats_heap_objects_total 24977 1648462713907
# HELP go_memstats_heap_reserved_bytes Process go heap reserved bytes
# TYPE go_memstats_heap_reserved_bytes gauge
go_memstats_heap_reserved_bytes 1.5597568e+07 1648462713907
# HELP go_memstats_gc_cpu_fraction_ratio Process go cpu used by gc. value is between 0 and 1
# TYPE go_memstats_gc_cpu_fraction_ratio gauge
go_memstats_gc_cpu_fraction_ratio 6.3805205330228665e-06 1648462713907
# HELP go_routines_total Number of goroutines that currently exist
# TYPE go_routines_total gauge
go_routines_total 44 1648462713907
jftrk_http_handle_request_sum{action="time_ms",domain="/api/v1/ping"} 7.778341000000002 1648462713907
jftrk_http_handle_request_count{action="time_ms",domain="/api/v1/ping"} 123 1648462713907
jftrk_http_successful_requests_count{action="count",domain="/api/v1/ping"} 123 1648462713907
# HELP jftrk_cache_topology_metrics_peers_total_free_cache_size_bytes Peers total free cache size
# TYPE jftrk_cache_topology_metrics_peers_total_free_cache_size_bytes gauge
jftrk_cache_topology_metrics_peers_total_free_cache_size_bytes 5.3685555205e+10 1648462713907
# HELP jftrk_cache_topology_metrics_peers_average_cache_used_ratio Peers average cache used
# TYPE jftrk_cache_topology_metrics_peers_average_cache_used_ratio gauge
jftrk_cache_topology_metrics_peers_average_cache_used_ratio 1.535995e+06 1648462713907
# HELP jftrk_cache_topology_metrics_peers_average_cache_free_ratio Peers average cache free
# TYPE jftrk_cache_topology_metrics_peers_average_cache_free_ratio gauge
jftrk_cache_topology_metrics_peers_average_cache_free_ratio 5.3685555205e+10 1648462713907
# HELP jftrk_cache_topology_metrics_peers_average_max_total_cache_size_ratio Peers average max total cache size
# TYPE jftrk_cache_topology_metrics_peers_average_max_total_cache_size_ratio gauge
jftrk_cache_topology_metrics_peers_average_max_total_cache_size_ratio 5.36870912e+10 1648462713907
# HELP jftrk_cache_topology_metrics_number_of_peers_total Number of peers
# TYPE jftrk_cache_topology_metrics_number_of_peers_total gauge
jftrk_cache_topology_metrics_number_of_peers_total 1 1648462713907
# HELP jftrk_cache_topology_metrics_number_of_groups_total Number of groups
# TYPE jftrk_cache_topology_metrics_number_of_groups_total gauge
jftrk_cache_topology_metrics_number_of_groups_total 1 1648462713907
# HELP jftrk_cache_topology_metrics_peers_total_cache_used_bytes Peers total cache used
# TYPE jftrk_cache_topology_metrics_peers_total_cache_used_bytes gauge
jftrk_cache_topology_metrics_peers_total_cache_used_bytes 1.535995e+06 1648462713907
# HELP jftrk_cache_topology_metrics_peers_total_max_cache_size_bytes Peers total max cache size
# TYPE jftrk_cache_topology_metrics_peers_total_max_cache_size_bytes gauge
jftrk_cache_topology_metrics_peers_total_max_cache_size_bytes 5.36870912e+10 1648462713907
# HELP jftrk_downloads_files_fetched_total Total number of files downloaded in PDN
# TYPE jftrk_downloads_files_fetched_total counter
jftrk_downloads_files_fetched_total 0 1648462713907
# HELP jftrk_downloads_bytes_served_total Total amount of bytes served to clients
# TYPE jftrk_downloads_bytes_served_total counter
jftrk_downloads_bytes_served_total 0 1648462713907
# HELP jftrk_downloads_bytes_fetched_total Total amount of bytes downloaded in PDN
# TYPE jftrk_downloads_bytes_fetched_total counter
jftrk_downloads_bytes_fetched_total 0 1648462713907
# HELP jftrk_downloads_release_bundles_total Total number of release bundles downloaded
# TYPE jftrk_downloads_release_bundles_total counter
jftrk_downloads_release_bundles_total 0 1648462713907
# HELP jftrk_downloads_file_providers_avg_ratio Average number of peers to download from per file
# TYPE jftrk_downloads_file_providers_avg_ratio gauge
jftrk_downloads_file_providers_avg_ratio 0 1648462713907
# HELP jftrk_downloads_speed_kbps_avg_ratio Average download speed in PDN (Kbps)
# TYPE jftrk_downloads_speed_kbps_avg_ratio gauge
jftrk_downloads_speed_kbps_avg_ratio 0 1648462713907
# HELP jftrk_downloads_errors_total Total download errors
# TYPE jftrk_downloads_errors_total counter
jftrk_downloads_errors_total 0 1648462713907
# HELP jftrk_downloads_files_served_total Total number of files served to clients
# TYPE jftrk_downloads_files_served_total counter
jftrk_downloads_files_served_total 0 1648462713907
# HELP sys_load_15 Host load average in the last 15 minutes
sys_load_15 2.7880859375 1648462713907
# HELP sys_load_1 Host load average in the last minute
sys_load_1 3.3408203125 1648462713907
# HELP sys_load_5 Host load average in the last 5 minutes
sys_load_5 3.0078125 1648462713907

PDN Node Metrics

Description: Gets the metrics for the PDN Node.
Since: 1.0.1
Security: Basic authorization (credentials are retrieved from the system.yaml).
Usage: GET /api/v1/metrics
Authorization: N/A
Content-Type: application/x-www-form-urlencoded

Example:

adoption_jfpdn_http_handle_request_sum{action="time_ms",domain="/api/v1/metrics"} 2026.6496839999998 1651583261702
adoption_jfpdn_http_handle_request_count{action="time_ms",domain="/api/v1/metrics"} 37 1651583261702
adoption_jfpdn_http_successful_requests_count{action="count",domain="/api/v1/metrics"} 37 1651583261702
# HELP app_disk_used_bytes Used bytes for app home directory disk device
# TYPE app_disk_used_bytes gauge
app_disk_used_bytes 5.30337615872e+11 1648462946518
# HELP app_disk_free_bytes Free bytes for app home directory disk device
# TYPE app_disk_free_bytes gauge
app_disk_free_bytes 4.69903347712e+11 1648462946518
# HELP app_io_counters_error Error
app_io_counters_error{error="not implemented yet"} 0 1648462946518
# HELP app_self_metrics_calc_seconds Total time to collect all metrics
# TYPE app_self_metrics_calc_seconds gauge
app_self_metrics_calc_seconds 0.050287282 1648462946518
# HELP app_self_metrics_total Count of collected metrics
# TYPE app_self_metrics_total gauge
app_self_metrics_total 28 1648462946518
# HELP go_memstats_heap_in_use_bytes Process go heap bytes in use
# TYPE go_memstats_heap_in_use_bytes gauge
go_memstats_heap_in_use_bytes 1.0665984e+07 1648462946518
# HELP go_memstats_heap_allocated_bytes Process go heap allocated bytes
# TYPE go_memstats_heap_allocated_bytes gauge
go_memstats_heap_allocated_bytes 9.024512e+06 1648462946518
# HELP go_memstats_heap_idle_bytes Process go heap idle bytes
# TYPE go_memstats_heap_idle_bytes gauge
go_memstats_heap_idle_bytes 4.99712e+06 1648462946518
# HELP go_memstats_heap_objects_total Process go heap number of objects
# TYPE go_memstats_heap_objects_total gauge
go_memstats_heap_objects_total 37384 1648462946518
# HELP go_memstats_heap_reserved_bytes Process go heap reserved bytes
# TYPE go_memstats_heap_reserved_bytes gauge
go_memstats_heap_reserved_bytes 1.5663104e+07 1648462946518
# HELP go_memstats_gc_cpu_fraction_ratio Process go cpu used by gc. value is between 0 and 1
# TYPE go_memstats_gc_cpu_fraction_ratio gauge
go_memstats_gc_cpu_fraction_ratio 0.020112994141442898 1648462946518
# HELP go_routines_total Number of goroutines that currently exist
# TYPE go_routines_total gauge
go_routines_total 30 1648462946518
# HELP jfpdn_cache_metrics_cache_used_bytes Cache used bytes
# TYPE jfpdn_cache_metrics_cache_used_bytes gauge
jfpdn_cache_metrics_cache_used_bytes 1.535995e+06 1648462946518
# HELP jfpdn_cache_metrics_cache_maximum_files_total Cache maximum files
# TYPE jfpdn_cache_metrics_cache_maximum_files_total gauge
jfpdn_cache_metrics_cache_maximum_files_total 30000 1648462946518
# HELP jfpdn_cache_metrics_cache_maximum_bytes Cache maximum bytes
# TYPE jfpdn_cache_metrics_cache_maximum_bytes gauge
jfpdn_cache_metrics_cache_maximum_bytes 5.36870912e+10 1648462946518
# HELP jfpdn_cache_metrics_cache_used_files_total Cache used files
# TYPE jfpdn_cache_metrics_cache_used_files_total gauge
jfpdn_cache_metrics_cache_used_files_total 3 1648462946518
# HELP jfpdn_downloads_speed_kbps_avg_ratio Average download speed in PDN (Kbps)
# TYPE jfpdn_downloads_speed_kbps_avg_ratio gauge
jfpdn_downloads_speed_kbps_avg_ratio 0 1648462946518
# HELP jfpdn_downloads_errors_total Total download errors
# TYPE jfpdn_downloads_errors_total counter
jfpdn_downloads_errors_total 0 1648462946518
# HELP jfpdn_downloads_files_served_total Total number of files served to clients
# TYPE jfpdn_downloads_files_served_total counter
jfpdn_downloads_files_served_total 0 1648462946518
# HELP jfpdn_downloads_files_fetched_total Total number of files downloaded in PDN
# TYPE jfpdn_downloads_files_fetched_total counter
jfpdn_downloads_files_fetched_total 0 1648462946518
# HELP jfpdn_downloads_bytes_served_total Total amount of bytes served to clients
# TYPE jfpdn_downloads_bytes_served_total counter
jfpdn_downloads_bytes_served_total 0 1648462946518
# HELP jfpdn_downloads_bytes_fetched_total Total amount of bytes downloaded in PDN
# TYPE jfpdn_downloads_bytes_fetched_total counter
jfpdn_downloads_bytes_fetched_total 0 1648462946518
# HELP jfpdn_downloads_release_bundles_total Total number of release bundles downloaded
# TYPE jfpdn_downloads_release_bundles_total counter
jfpdn_downloads_release_bundles_total 0 1648462946518
# HELP jfpdn_downloads_file_providers_avg_ratio Average number of peers to download from per file
# TYPE jfpdn_downloads_file_providers_avg_ratio gauge
jfpdn_downloads_file_providers_avg_ratio 0 1648462946518
# TYPE sys_cpu_ratio gauge
sys_cpu_ratio 0.16049382709107227 1648462946518
# HELP sys_load_1 Host load average in the last minute
sys_load_1 3.4912109375 1648462946518
# HELP sys_load_5 Host load average in the last 5 minutes
sys_load_5 3.27685546875 1648462946518
# HELP sys_load_15 Host load average in the last 15 minutes
sys_load_15 2.9560546875 1648462946518
# HELP sys_memory_used_bytes Host used virtual memory
# TYPE sys_memory_used_bytes gauge
sys_memory_used_bytes 1.9079716864e+10 1648462946518
# HELP sys_memory_free_bytes Host free virtual memory
# TYPE sys_memory_free_bytes gauge
sys_memory_free_bytes 6.56072704e+08 1648462946518