doc/user/cwl/costanalyzer.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: Analyzing workflow cost (cloud only)
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 {% include 'tutorial_expectations' %}
  13
  14 {% include 'notebox_begin' %}
  15
  16 Cost information is generally only available when Arvados runs in a cloud environment and @arvados-dispatch-cloud@ is used to dispatch containers. The per node-hour price for each defined InstanceType must be supplied in "config.yml":{{site.baseurl}}/admin/config.html.
  17
  18 {% include 'notebox_end' %}
  19
  20 The @arv-cluster-activity@ program can be used to analyze cluster usage and cost over a time period.
  21
  22 h2. Installation
  23
  24 The @arv-cluster-activity@ tool can be installed from a distribution package or PyPI.
  25
  26 h2. Option 1: Install from distribution packages
  27
  28 First, "add the appropriate package repository for your distribution":{{ site.baseurl }}/install/packages.html.
  29
  30 {% assign arvados_component = 'python3-arvados-cluster-activity' %}
  31
  32 {% include 'install_packages' %}
  33
  34 h2. Option 2: Install with pip
  35
  36 Run @pip install arvados-cluster-activity[prometheus]@ in an appropriate installation environment, such as a virtualenv.
  37
  38 Note:
  39
  40 Support for fetching Prometheus metrics depends on Pandas and NumPy.  If these dependencies pose a problem, you can install the cluster activity tool without Prometheus support by omitting it from @pip install@.
  41
  42 The Cluster Activity report uses the Arvados Python SDK, which uses @pycurl@, which depends on the @libcurl@ C library.  To build the module you may have to first install additional packages.  On Debian-based distributions you can install them by running:
  43
  44 <notextile>
  45 <pre><code># <span class="userinput">apt install git build-essential python3-dev libcurl4-openssl-dev libssl-dev</span>
  46 </code></pre>
  47 </notextile>
  48
  49 h2(#syntax). Syntax
  50
  51 The @arv-cluster-activity@ tool has a number of command line arguments:
  52
  53 <notextile>
  54 <pre><code>~$ <span class="userinput">arv-cluster-activity --help</span>
  55 usage: arv-cluster-activity [-h] [--start START] [--end END] [--days DAYS] [--cost-report-file COST_REPORT_FILE] [--include-workflow-steps] [--columns COLUMNS] [--exclude EXCLUDE]
  56                             [--html-report-file HTML_REPORT_FILE] [--version] [--cluster CLUSTER] [--prometheus-auth PROMETHEUS_AUTH]
  57
  58 options:
  59   -h, --help            show this help message and exit
  60   --start START         Start date for the report in YYYY-MM-DD format (UTC) (or use --days)
  61   --end END             End date for the report in YYYY-MM-DD format (UTC), default "now"
  62   --days DAYS           Number of days before "end" to start the report (or use --start)
  63   --cost-report-file COST_REPORT_FILE
  64                         Export cost report to specified CSV file
  65   --include-workflow-steps
  66                         Include individual workflow steps (optional)
  67   --columns COLUMNS     Cost report columns (optional), must be comma separated with no spaces between column names. Available columns are:
  68                         Project, ProjectUUID, Workflow,
  69                         WorkflowUUID, Step, StepUUID, Sample, SampleUUID, User, UserUUID, Submitted, Started, Runtime, Cost
  70   --exclude EXCLUDE     Exclude workflows containing this substring (may be a regular expression)
  71   --html-report-file HTML_REPORT_FILE
  72                         Export HTML report to specified file
  73   --version             Print version and exit.
  74   --cluster CLUSTER     Cluster to query for prometheus stats
  75   --prometheus-auth PROMETHEUS_AUTH
  76                         Authorization file with prometheus info
  77 </code></pre>
  78 </notextile>
  79
  80 h2(#Credentials). Credentials
  81
  82 To access the Arvados host, the tool will read default credentials from @~/.config/aravdos/settings.conf@ or use the standard @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ environment variables.
  83
  84 The cluster report tool will also fetch metrics from Prometheus, if available.  This can be passed in an environment file using @--prometheus-auth@, or set as environment variables.
  85
  86 <pre>
  87 PROMETHEUS_HOST=https://your.prometheus.server.example.com
  88 PROMETHEUS_USER=admin
  89 PROMETHEUS_PASSWORD=password
  90 </pre>
  91
  92 @PROMETHEUS_USER@ and @PROMETHEUS_PASSWORD@ will be passed in an @Authorization@ header using HTTP Basic authentication.
  93
  94 Alternately, instead of @PROMETHEUS_USER@ and @PROMETHEUS_PASSWORD@ you can provide @PROMETHEUS_APIKEY@.  This will be passed in as a Bearer token (@Authorization: Bearer <APIKEY>@).
  95
  96 h2(#example). Example usage
  97
  98 <notextile>
  99 <pre><code>~$ <span class="userinput">arv-cluster-activity \
 100     --days 90
 101     --include-workflow-steps \
 102     --prometheus-auth prometheus.env \
 103     --cost-report-file report.csv \
 104     --html-report-file report.html</span>
 105 INFO:root:Exporting workflow runs 0 - 5
 106 INFO:root:Getting workflow steps
 107 INFO:root:Got workflow steps 0 - 2
 108 INFO:root:Getting container hours time series
 109 INFO:root:Getting data usage time series
 110 </code></pre>
 111 </notextile>
 112
 113 !sample-cluster-activity-report.png!