Commit fde50cbd authored by wkalt's avatar wkalt

(PDB-698) Convert from dashes to underscores in API commands and responses

This patch changes our API commands and responses to use underscores instead of
dashes, which will make it easier to interface with PDB using languages like
javascript and python.

This bumps the version of replace-facts, replace-catalog, and store-report,
and changes our subquery operators to use underscores as well.
parent 1aafe063
......@@ -60,8 +60,8 @@ test_name "export and import tools" do
assert_equal(agents.length, result_node_statuses.length, "Should only have 1 node")
node = result_node_statuses.first
assert(node["catalog-timestamp"].nil?, "Should not have a catalog timestamp")
assert(node["facts-timestamp"], "Should have a facts timestamp")
assert(node["catalog_timestamp"].nil?, "Should not have a catalog timestamp")
assert(node["facts_timestamp"], "Should have a facts timestamp")
end
export_file1 = "./puppetdb-export1.tar.gz"
......@@ -96,8 +96,8 @@ test_name "export and import tools" do
assert_equal(agents.length, result_node_statuses.length, "Should only have 1 node")
node = result_node_statuses.first
assert(node["catalog-timestamp"].nil?, "Should not have a catalog timestamp")
assert(node["facts-timestamp"], "Should have a facts timestamp")
assert(node["catalog_timestamp"].nil?, "Should not have a catalog timestamp")
assert(node["facts_timestamp"], "Should have a facts timestamp")
end
end
......@@ -42,7 +42,7 @@ test_name "structured and trusted facts should be available through facts termin
step "create a custom structured fact" do
payload = <<-EOM
-H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"command":"replace facts","version":3, \
-d '{"command":"replace facts","version":4, \
"payload":{"environment":"DEV","name":"#{master}", \
"values":{"my_structured_fact":#{JSON.generate(structured_data)}}}}' http://localhost:8080/v4/commands
EOM
......
......@@ -33,9 +33,9 @@ test_name "validation of basic PuppetDB resource event queries" do
query = <<EOM
["and",
["=", "certname", "#{agent.node_name}"],
["=", "resource-type", "Notify"],
["=", "resource_type", "Notify"],
["not",
["=", "resource-title", "bunk"]],
["=", "resource_title", "bunk"]],
["or",
["=", "status", "success"],
["=", "status", "booyah"]],
......
......@@ -108,9 +108,9 @@ MANIFEST
query = <<EOM
["and",
["=", "certname", "#{agent.node_name}"],
["=", "resource-type", "Notify"],
["=", "resource_type", "Notify"],
["not",
["=", "resource-title", "bunk"]],
["=", "resource_title", "bunk"]],
["or",
["=", "status", "success"],
["=", "status", "booyah"]],
......
......@@ -34,16 +34,16 @@ test_name "basic validation of puppet report submission" do
# typical puppet run there are a bunch of "Schedule" resources that will
# always show up as skipped. Here we filter them out because they're
# not really interesting for this test.
events = events.reject {|x| x["resource-type"] == "Schedule" }
events = events.reject {|x| x["resource_type"] == "Schedule" }
assert_equal(1, events.length)
event = events[0]
assert_equal("Notify", event["resource-type"], "resource-type doesn't match!")
assert_equal("hi", event["resource-title"], "resource-title doesn't match!")
assert_equal("Notify", event["resource_type"], "resource_type doesn't match!")
assert_equal("hi", event["resource_title"], "resource_title doesn't match!")
assert_equal("message", event["property"], "property doesn't match!")
assert_equal("Hi #{agent.node_name}", event["new-value"], "new-value doesn't match!")
assert_equal("Hi #{agent.node_name}", event["new_value"], "new_value doesn't match!")
end
end
......@@ -17,16 +17,16 @@ test_name "validate matching transaction UUIDs in agent report and catalog" do
agents.each do |agent|
# Query for all of the reports for this node, but we only care about the most recent one
result = on database, %Q|curl -G http://localhost:8080/v4/reports --data 'query=["=",%20"certname",%20"#{agent.node_name}"]' --data 'order-by=[{"field":"receive-time","order":"desc"}]'|
result = on database, %Q|curl -G http://localhost:8080/v4/reports --data 'query=["=",%20"certname",%20"#{agent.node_name}"]' --data 'order_by=[{"field":"receive_time","order":"desc"}]'|
report = JSON.parse(result.stdout)[0]
# Query for the most recent catalog for this node
result = on database, %Q|curl -G http://localhost:8080/v4/catalogs/#{agent.node_name}|
catalog = JSON.parse(result.stdout)
report_uuid = report['transaction-uuid']
catalog_uuid = catalog['transaction-uuid']
report_format = report['report-format']
report_uuid = report['transaction_uuid']
catalog_uuid = catalog['transaction_uuid']
report_format = report['report_format']
if report_format < 4
assert_equal(nil, report_uuid, 'Transaction UUID should be nil in reports before format 4')
......
......@@ -4,10 +4,9 @@ layout: default
canonical: "/puppetdb/latest/api/commands.html"
---
[factsv3]: ./wire_format/facts_format_v3.html
[catalogv5]: ./wire_format/catalog_format_v5.html
[reportv3]: ./wire_format/report_format_v3.html
[reportv4]: ./wire_format/report_format_v4.html
[factsv4]: ./wire_format/facts_format_v4.html
[catalogv6]: ./wire_format/catalog_format_v6.html
[reportv5]: ./wire_format/report_format_v5.html
Commands are used to change PuppetDB's
model of a population. Commands are represented by `command objects`,
......@@ -68,23 +67,22 @@ processed.
## List of Commands
### "replace catalog", version 5
### "replace catalog", version 6
Version 5 differs from version 4 by added support of a producer-timestamp
field. This field is currently populated by the master, but will eventually
be populated by agents to help ensure a consistent order of events in a
multiple-master setup. Previous versions of the command will store a `null`
value for this field.
Version 6 differs from version 5 only in that all field names that were
previously separated by dashes are separated by underscores.
The payload is expected to be a Puppet catalog, as a JSON object, conforming
exactly to the [catalog wire format v5][catalogv5]. Extra or missing fields
exactly to the [catalog wire format v6][catalogv6]. Extra or missing fields
are an error.
### "replace facts", version 3
### "replace facts", version 4
Similar to version 5 of replace catalog, this version of replace facts adds support
for the producer-timestamp field that will eventually be used for agent
timekeeping. See [fact wire format v3][factsv3] for more information on the
Similar to version 6 of replace catalog, this version of replace facts differs
from version 3 only in that the previously dashed fields are now
underscore-separated.
See [fact wire format v3][factsv3] for more information on the
payload of this command.
### "deactivate node", version 2
......@@ -93,26 +91,15 @@ The payload is expected to be the name of a node, as a raw JSON string, which wi
effective as of the time the command is *processed*. Serialization of the payload is no
longer required.
### "store report", version 3
> **Note:** This version is deprecated, use the latest version instead.
Similar to replace catalog version 4, this version of store report adds support
for environments and creates an explicit link between command version and wire
format version. This is a backward compatible change with version 2.
The payload is expected to be a report, containing events that occurred on Puppet
resources. It is structured as a JSON object, conforming to the
[report wire format v3][reportv3].
### "store report", version 4
### "store report", version 5
This version of store reports, includes a new top level `status` field to store the overall status
of a puppet run.
As with version 4 or replace facts and version 6 of replace catalog, the
version 5 store report command differs from version 4 only in that previously
dash-separated fields are underscore-separated.
The payload is expected to be a report, containing events that occurred on Puppet
resources. It is structured as a JSON object, conforming to the
[report wire format v4][reportv4].
[report wire format v5][reportv5].
## Examples using curl
......
......@@ -34,17 +34,17 @@ This endpoint builds on top of the [`event-counts`][event-counts] endpoint, and
* `query`: Required. A JSON array of query predicates in prefix form (`["<OPERATOR>", "<FIELD>", "<VALUE>"]`).
This query is forwarded to the [`events`][events] endpoint - see there for additional documentation. For general info about queries, see [the page on query structure.][query]
* `summarize-by`: Required. A string specifying which type of object you'd like count. Supported values are
`resource`, `containing-class`, and `certname`.
* `summarize_by`: Required. A string specifying which type of object you'd like count. Supported values are
`resource`, `containing_class`, and `certname`.
* `count-by`: Optional. A string specifying what type of object is counted when building up the counts of
* `count_by`: Optional. A string specifying what type of object is counted when building up the counts of
`successes`, `failures`, `noops`, and `skips`. Supported values are `resource` (default) and `certname`.
* `counts-filter`: Optional. A JSON array of query predicates in the usual prefix form. This query is applied to
* `counts_filter`: Optional. A JSON array of query predicates in the usual prefix form. This query is applied to
the final event-counts output, but before the results are aggregated. Supported operators are `=`, `>`, `<`,
`>=`, and `<=`. Supported fields are `failures`, `successes`, `noops`, and `skips`.
* `distinct-resources`: Optional. (EXPERIMENTAL: it is possible that the behavior
* `distinct_resources`: Optional. (EXPERIMENTAL: it is possible that the behavior
of this parameter may change in future releases.) This parameter is passed along
to the [`event`][events] query - see there for additional documentation.
......@@ -75,7 +75,7 @@ You can use [`curl`][curl] to query information about aggregated resource event
curl -G 'http://localhost:8080/v4/aggregate-event-counts'
--data-urlencode 'query=["=", "certname", "foo.local"]' \
--data-urlencode 'summarize-by=containing-class'
--data-urlencode 'summarize_by=containing_class'
## No Paging
......
......@@ -30,11 +30,11 @@ See [the Operators page.](./operators.html)
* `name` (string): the certname associated with the catalog
* `version` (string): an arbitrary string that uniquely identifies each catalog for a node
* `environment` (string): the environment associated with the catalog's certname
* `transaction-uuid` (string): a string used to tie a catalog to a report from the same puppet run
* `transaction_uuid` (string): a string used to tie a catalog to a report from the same puppet run
* `hash` (string): sha1 hash of the resources of associated with a node's most
recent catalog
* `producer-timestamp` (string): a string representing the time at which the
`replace-catalog` command for a given catalog was submitted from the master.
* `producer_timestamp` (string): a string representing the time at which the
`replace_catalog` command for a given catalog was submitted from the master.
Generation of this field will be pushed back to the agent in a later release, so it
should not be relied on in its current form.
......@@ -50,8 +50,8 @@ the form:
"version" : <catalog version>,
"environment" : <catalog environment>,
"hash" : <sha1 sum of catalog resources>,
"transaction-uuid" : <string to identify puppet run>,
"producer-timestamp": <time of transmission by master>,
"transaction_uuid" : <string to identify puppet run>,
"producer_timestamp": <time of transmission by master>,
"resources" : <list of objects representing resources in the catalog>,
"edges" : <list of objects representing relationships between resources>
}
......@@ -68,8 +68,8 @@ This query will return the complete list of catalogs:
"name" : "yo.delivery.puppetlabs.net",
"hash" : "62cdc40a78750144b1e1ee06638ac2dd0eeb9a46",
"version" : "e4c339f",
"transaction-uuid" : "53b72442-3b73-11e3-94a8-1b34ef7fdc95",
"producer-timestamp": "2014-10-13T20:46:00.000Z",
"transaction_uuid" : "53b72442-3b73-11e3-94a8-1b34ef7fdc95",
"producer_timestamp": "2014-10-13T20:46:00.000Z",
"environment" : "production",
"edges" : [...],
"resources" : [...]
......@@ -78,23 +78,23 @@ This query will return the complete list of catalogs:
"name" : "foo.delivery.puppetlabs.net",
"hash" : "e1a4610ecbb3483fa5e637f42374b2cc46d06474",
"version" : "449720",
"transaction-uuid" : "9a3c8da6-f48c-4567-b24e-ddae5f80a6c6",
"producer-timestamp": "2014-11-20T02:15:20.861Z",
"transaction_uuid" : "9a3c8da6-f48c-4567-b24e-ddae5f80a6c6",
"producer_timestamp": "2014-11-20T02:15:20.861Z",
"environment" : "production",
"edges" : [...],
"resources" : [...]
} ]
This query will return all catalogs with producer-timestamp after 2014-11-19:
This query will return all catalogs with producer_timestamp after 2014-11-19:
curl -X GET http://puppetdb:8080/v4/catalogs --data-urlencode 'query=[">","producer-timestamp","2014-11-19"]'
curl -X GET http://puppetdb:8080/v4/catalogs --data-urlencode 'query=[">","producer_timestamp","2014-11-19"]'
[ {
"name" : "foo.delivery.puppetlabs.net",
"hash" : "e1a4610ecbb3483fa5e637f42374b2cc46d06474",
"version" : "449720",
"transaction-uuid" : "9a3c8da6-f48c-4567-b24e-ddae5f80a6c6",
"producer-timestamp": "2014-11-20T02:15:20.861Z",
"transaction_uuid" : "9a3c8da6-f48c-4567-b24e-ddae5f80a6c6",
"producer_timestamp": "2014-11-20T02:15:20.861Z",
"environment" : "production",
"edges" : [...],
"resources" : [...]
......@@ -119,8 +119,8 @@ a JSON error message if the catalog is not found:
"name" : "yo.delivery.puppetlabs.net",
"hash" : "62cdc40a78750144b1e1ee06638ac2dd0eeb9a46",
"version" : "e4c339f",
"transaction-uuid" : "53b72442-3b73-11e3-94a8-1b34ef7fdc95",
"producer-timestamp": "2014-10-13T20:46:00.000Z",
"transaction_uuid" : "53b72442-3b73-11e3-94a8-1b34ef7fdc95",
"producer_timestamp": "2014-10-13T20:46:00.000Z",
"environment" : "production",
"edges" : [...],
"resources" : [...]
......
......@@ -24,7 +24,7 @@ Once this information is stored in PuppetDB, it can be queried in various ways.
## `GET /v4/event-counts`
This will return count information about all of the resource events matching the given query.
For a given object type (resource, containing-class, or node), you can retrieve counts of the
For a given object type (resource, containing_class, or node), you can retrieve counts of the
number of events on objects of that type that had a status of `success`, `failure`, `noop`,
or `skip`.
......@@ -35,18 +35,18 @@ See the [`events`][events] endpoint for additional documentation as this endpoin
* `query`: Required. A JSON array of query predicates in prefix form (`["<OPERATOR>", "<FIELD>", "<VALUE>"]`).
This query is forwarded to the [`events`][events] endpoint - see there for additional documentation. For general info about queries, see [the page on query structure.][query]
* `summarize-by`: Required. A string specifying which type of object you'd like to see counts for.
Supported values are `resource`, `containing-class`, and `certname`.
* `summarize_by`: Required. A string specifying which type of object you'd like to see counts for.
Supported values are `resource`, `containing_class`, and `certname`.
* `count-by`: Optional. A string specifying what type of object is counted when building up the
* `count_by`: Optional. A string specifying what type of object is counted when building up the
counts of `successes`, `failures`, `noops`, and `skips`. Supported values are `resource` (default)
and `certname`.
* `counts-filter`: Optional. A JSON array of query predicates in the usual prefix form. This query
* `counts_filter`: Optional. A JSON array of query predicates in the usual prefix form. This query
is applied to the final event counts output. Supported operators are `=`, `>`, `<`, `>=`, and `<=`.
Supported fields are `failures`, `successes`, `noops`, and `skips`.
* `distinct-resources`: Optional. (EXPERIMENTAL: it is possible that the behavior
* `distinct_resources`: Optional. (EXPERIMENTAL: it is possible that the behavior
of this parameter may change in future releases.) This parameter is passed along
to the [`event`][events] query - see there for additional documentation.
......@@ -63,16 +63,16 @@ This endpoint builds on top of the [`events`][events] endpoint, and supports all
The response is a JSON array of maps. Each map contains the counts of events that matched the input
parameters. The events are counted based on their statuses: `failures`, `successes`, `noops`, `skips`.
The maps also contain additional data about which object the events occurred on. The `subject-type`
is the value that was used to summarize by (and therefore should match the input value to `summarize-by`).
The maps also contain additional data about which object the events occurred on. The `subject_type`
is the value that was used to summarize by (and therefore should match the input value to `summarize_by`).
The `subject` map contains specific data about the object the event occurred on, and will vary based on
the value specified for `summarize-by`.
the value specified for `summarize_by`.
When summarizing by `certname`, the `subject` will contain a `title` key:
[
{
"subject-type": "certname",
"subject_type": "certname",
"subject": { "title": "foo.local" },
"failures": 0,
"successes": 2,
......@@ -80,7 +80,7 @@ When summarizing by `certname`, the `subject` will contain a `title` key:
"skips": 1
},
{
"subject-type": "certname",
"subject_type": "certname",
"subject": { "title": "bar.local" },
"failures": 1,
"successes": 0,
......@@ -93,7 +93,7 @@ When summarizing by `resource`, the `subject` will contain a `type` and `title`
[
{
"subject-type": "resource",
"subject_type": "resource",
"subject": { "type": "Notify", "title": "Foo happened" },
"failures": 0,
"successes": 1,
......@@ -101,7 +101,7 @@ When summarizing by `resource`, the `subject` will contain a `type` and `title`
"skips": 0
},
{
"subject-type": "resource",
"subject_type": "resource",
"subject": { "type": "Notify", "title": "Bar happened" },
"failures": 0,
"successes": 0,
......@@ -110,11 +110,11 @@ When summarizing by `resource`, the `subject` will contain a `type` and `title`
}
]
When summarizing by `containing-class`, the `subject` will contain a `title` key:
When summarizing by `containing_class`, the `subject` will contain a `title` key:
[
{
"subject-type": "containing-class",
"subject_type": "containing_class",
"subject": { "title": "Foo::Class" },
"failures": 1,
"successes": 2,
......@@ -122,7 +122,7 @@ When summarizing by `containing-class`, the `subject` will contain a `title` key
"skips": 1
},
{
"subject-type": "containing-class",
"subject_type": "containing_class",
"subject": { "title": null },
"failures": 0,
"successes": 0,
......@@ -137,9 +137,9 @@ You can use [`curl`][curl] to query information about resource event counts like
curl -G 'http://localhost:8080/v4/event-counts' \
--data-urlencode 'query=["=", "certname", "foo.local"]' \
--data-urlencode 'summarize-by=resource' \
--data-urlencode 'count-by=certname' \
--data-urlencode 'counts-filter=[">", "failures", 0]'
--data-urlencode 'summarize_by=resource' \
--data-urlencode 'count_by=certname' \
--data-urlencode 'counts_filter=[">", "failures", 0]'
## Paging
......
......@@ -33,21 +33,21 @@ are generated from Puppet reports.)
* `query`: Required. A JSON array of query predicates, in prefix form (`["<OPERATOR>", "<FIELD>", "<VALUE>"]`). See the sections below for the supported operators and fields. For general info about queries, see [the page on query structure.][query]
* `distinct-resources`: Optional. Boolean. (I.e. `distinct-resources=true`.) (EXPERIMENTAL: it is possible that the behavior
* `distinct_resources`: Optional. Boolean. (I.e. `distinct_resources=true`.) (EXPERIMENTAL: it is possible that the behavior
of this parameter may change in future releases.) If specified, the result set will only return the most recent event for a given resource on a given node.
For example: if the resource `File[/tmp/foo]` was failing on some node
but has since been fixed and is now succeeding, then a "normal" event query might
return both the success and failure events. A query with `distinct-resources=true`
return both the success and failure events. A query with `distinct_resources=true`
would only return the success event, since it's the most recent event for that resource.
Since a `distinct-resources` query can be expensive, it requires a limited
Since a `distinct_resources` query can be expensive, it requires a limited
window of time to examine. Use the `distinct-start-time` and
`distinct-end-time` parameters to define this interval.
Issuing a `distinct-resources` query without specifying both of these parameters will cause an error.
Issuing a `distinct_resources` query without specifying both of these parameters will cause an error.
* `distinct-start-time`: Used with `distinct-resources`. The start of the window of time to examine, as an [ISO-8601][8601] compatible date/time string.
* `distinct-end-time`: Used with `distinct-resources`. The end of the window of time to examine, as an [ISO-8601][8601] compatible date/time string.
* `distinct-start-time`: Used with `distinct_resources`. The start of the window of time to examine, as an [ISO-8601][8601] compatible date/time string.
* `distinct-end-time`: Used with `distinct_resources`. The end of the window of time to examine, as an [ISO-8601][8601] compatible date/time string.
### Query Operators
......@@ -79,30 +79,30 @@ operators.
supports the inequality operators. Timestamps are always [ISO-8601][8601]
compatible date/time strings.
* `run-start-time` (timestamp): the timestamp (from the puppet agent) at which the puppet run began. This field
* `run_start_time` (timestamp): the timestamp (from the puppet agent) at which the puppet run began. This field
supports the inequality operators. Timestamps are always [ISO-8601][8601]
compatible date/time strings.
* `run-end-time` (timestamp): the timestamp (from the puppet agent) at which the puppet run finished. This field
* `run_end_time` (timestamp): the timestamp (from the puppet agent) at which the puppet run finished. This field
supports the inequality operators. Timestamps are always [ISO-8601][8601]
compatible date/time strings.
* `report-receive-time` (timestamp): the timestamp (from the PuppetDB server) at which the puppet report was
* `report_receive_time` (timestamp): the timestamp (from the PuppetDB server) at which the puppet report was
received. This field supports the inequality operators. Timestamps are always [ISO-8601][8601]
compatible date/time strings.
* `resource-type` (string, with first letter always capitalized): the type of resource that the event occurred on; e.g., `File`, `Package`, etc.
* `resource_type` (string, with first letter always capitalized): the type of resource that the event occurred on; e.g., `File`, `Package`, etc.
* `resource-title` (string): the title of the resource that the event occurred on.
* `resource_title` (string): the title of the resource that the event occurred on.
* `property` (string or null): the property/parameter of the resource that the event occurred on; e.g., for a
`Package` resource, this field might have a value of `ensure`. NOTE: this field
may contain `NULL` values; see notes above.
* `new-value` (string or null): the new value that Puppet was attempting to set for the specified resource
* `new_value` (string or null): the new value that Puppet was attempting to set for the specified resource
property. NOTE: this field may contain `NULL` values; see notes above.
* `old-value` (string or null): the previous value of the resource property, which Puppet was attempting to
* `old_value` (string or null): the previous value of the resource property, which Puppet was attempting to
change. NOTE: this field may contain `NULL` values; see notes above.
* `message` (string or null): a description (supplied by the resource provider) of what happened during the
......@@ -114,18 +114,18 @@ operators.
* `line` (number or null): the line (of the containing manifest file) at which the resource definition
can be found. NOTE: this field may contain `NULL` values; see notes above.
* `containing-class` (string or null): the Puppet class where this resource is declared. NOTE: this field may
* `containing_class` (string or null): the Puppet class where this resource is declared. NOTE: this field may
contain `NULL` values; see notes above.
* `latest-report?` (boolean): whether the event occurred in the most recent Puppet run (per-node). NOTE: the
* `latest_report?` (boolean): whether the event occurred in the most recent Puppet run (per-node). NOTE: the
value of this field is always boolean (`true` or `false` without quotes), and it
is not supported by the regex match operator.
* `environment` (string): the environment associated with the reporting node.
* `configuration-version` (string): an identifier string that puppet uses to match a specific catalog for a node to a specific puppet run.
* `configuration_version` (string): an identifier string that puppet uses to match a specific catalog for a node to a specific puppet run.
* `containment-path` (array of strings, where each string is a containment path element): the containment path associated with the event, as an ordered array that ends with the most specific containing element.
* `containment_path` (array of strings, where each string is a containment path element): the containment path associated with the event, as an ordered array that ends with the most specific containing element.
### Response Format
......@@ -135,41 +135,41 @@ The array is unordered.
[
{
"certname": "foo.localdomain",
"old-value": "absent",
"old_value": "absent",
"property": "ensure",
"timestamp": "2012-10-30T19:01:05.000Z",
"resource-type": "File",
"resource-title": "/tmp/reportingfoo",
"new-value": "file",
"resource_type": "File",
"resource_title": "/tmp/reportingfoo",
"new_value": "file",
"message": "defined content as '{md5}49f68a5c8493ec2c0bf489821c21fc3b'",
"report": "38ff2aef3ffb7800fe85b322280ade2b867c8d27",
"status": "success",
"file": "/home/user/path/to/manifest.pp",
"line": 6,
"containment-path": [ "Stage[main]", "Foo", "File[/tmp/reportingfoo]" ],
"containing-class": "Foo",
"run-start-time": "2012-10-30T19:00:00.000Z",
"run-end-time": "2012-10-30T19:05:00.000Z",
"report-receive-time": "2012-10-30T19:06:00.000Z"
"containment_path": [ "Stage[main]", "Foo", "File[/tmp/reportingfoo]" ],
"containing_class": "Foo",
"run_start_time": "2012-10-30T19:00:00.000Z",
"run_end_time": "2012-10-30T19:05:00.000Z",
"report_receive_time": "2012-10-30T19:06:00.000Z"
},
{
"certname": "foo.localdomain",
"old-value": "absent",
"old_value": "absent",
"property": "message",
"timestamp": "2012-10-30T19:01:05.000Z",
"resource-type": "Notify",
"resource-title": "notify, yo",
"new-value": "notify, yo",
"resource_type": "Notify",
"resource_title": "notify, yo",
"new_value": "notify, yo",
"message": "defined 'message' as 'notify, yo'",
"report": "38ff2aef3ffb7800fe85b322280ade2b867c8d27",
"status": "success",
"file": "/home/user/path/to/manifest.pp",
"line": 10,
"containment-path": [ "Stage[main]", "", "Node[default]", "Notify[notify, yo]" ],
"containing-class": null,
"run-start-time": "2012-10-30T19:00:00.000Z",
"run-end-time": "2012-10-30T19:05:00.000Z",
"report-receive-time": "2012-10-30T19:06:00.000Z"
"containment_path": [ "Stage[main]", "", "Node[default]", "Notify[notify, yo]" ],
"containing_class": null,
"run_start_time": "2012-10-30T19:00:00.000Z",
"run_end_time": "2012-10-30T19:05:00.000Z",
"report_receive_time": "2012-10-30T19:06:00.000Z"
}
]
......@@ -195,11 +195,11 @@ type 'Service':
["and", ["=", "status", "failure"],
["~", "certname", "^foo\\."],
["=", "resource-type", "Service"]]
["=", "resource_type", "Service"]]
To retrieve latest events that are tied to the class found in your update.pp file:
["and", ["=", "latest-report?", true],
["and", ["=", "latest_report?", true],
["~", "file", "update.pp"]]
## Paging
......
......@@ -80,7 +80,7 @@ Subquery against `/fact-contents` to get all remotely-authenticated trusted fact
curl -X GET http://localhost:8080/v4/facts --data-urlencode 'query=["in", ["name","certname"],
["extract",["name","certname"],
["select-fact-contents", ["~>", "path", [".*", "authenticated"]]]]]'
["select_fact_contents", ["~>", "path", [".*", "authenticated"]]]]]'
[ {
"value" : {
......
......@@ -32,12 +32,12 @@ See [the Operators page.](./operators.html)
* `environment` (string): the environment associated with the fact
* `timestamp` (string): the most recent time of fact submission from the
associated certname
* `producer-timestamp` (string): the most recent time of fact submission for
* `producer_timestamp` (string): the most recent time of fact submission for
the relevant certname from the master. Generation of this field will
be pushed back to the agent in a later release, so it should not be relied on
in its current form (use the `timestamp` field instead.)
* `hash` (string): a hash of the factset's certname, environment,
timestamp, facts, and producer-timestamp.
timestamp, facts, and producer_timestamp.
### Response Format
......@@ -51,7 +51,7 @@ the form:
"certname": <node name>,
"environment": <node environment>,
"timestamp": <time of last fact submission>,
"producer-timestamp": <time of command submission from master>,
"producer_timestamp": <time of command submission from master>,
"facts": <facts for node>,
"hash": <sha1 sum of "facts" value>
}
......@@ -75,7 +75,7 @@ Get all factsets with updated after "2014-07-21T16:13:44.334Z":
Get all factsets corresponding to nodes running Darwin:
curl -X GET http://puppetdb:8080/v4/factsets --data-urlencode 'query=["in",
"certname", ["extract", "certname", ["select-facts", ["and", ["=", "name",
"certname", ["extract", "certname", ["select_facts", ["and", ["=", "name",
"operatingsystem"], ["=", "value", "Darwin"]]]]]'
which returns
......@@ -88,7 +88,7 @@ which returns
},
"timestamp" : "2014-07-25T16:39:06.265Z",
"producer-timestamp" : "2014-07-25T16:39:06.265Z",
"producer_timestamp" : "2014-07-25T16:39:06.265Z",
"environment" : "production",
"certname" : "desktop.localdomain",
"hash": "b920822bc3872c9e2977cf40f87811393ead71aa"
......
......@@ -36,17 +36,17 @@ The below fields are allowed as filter criteria and are returned in all response
* `certname` (string): the name of the node that the report was received from.
* `catalog-environment` (string): the environment for the last received catalog
* `catalog_environment` (string): the environment for the last received catalog
* `facts-environment` (string): the environment for the last received fact set
* `facts_environment` (string): the environment for the last received fact set
* `report-environment` (string): the environment for the last received report
* `report_environment` (string): the environment for the last received report
* `catalog-timestamp` (timestamp): last time a catalog was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.
* `catalog_timestamp` (timestamp): last time a catalog was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.
* `facts-timestamp` (timestamp): last time a fact set was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.
* `facts_timestamp` (timestamp): last time a fact set was received. Timestamps are always [ISO-8601][8601] compatible date/time strings.
* `report-timestamp` (timestamp): last time a report run was complete. Timestamps are always [ISO-8601][8601] compatible date/time strings.
* `report_timestamp` (timestamp): last time a report run was complete. Timestamps are always [ISO-8601][8601] compatible date/time strings.
* `["fact", <FACT NAME>]` (string, coercible to number): the value of `<FACT NAME>` for a node. Inequality operators are allowed, and will skip non-numeric values.
......@@ -60,12 +60,12 @@ The response is a JSON array of hashes, where each hash has the form:
{"certname": <string>,
"deactivated": <timestamp or null>,
"catalog-timestamp": <timestamp or null>,
"facts-timestamp": <timestamp or null>,
"report-timestamp": <timestamp or null>,
"catalog-environment": <string or null>,
"facts-environment": <string or null>,
"report-environment": <string or null>}
"catalog_timestamp": <timestamp or null>,
"facts_timestamp": <timestamp or null>,
"report_timestamp": <timestamp or null>,
"catalog_environment": <string or null>,
"facts_environment": <string or null>,
"report_environment": <string or null>}
At least one of the `-timestamp` fields will be non-null.
......@@ -106,12 +106,12 @@ The response is a single hash, of the same form used for the plain `nodes` endpo
{"certname": <string>,
"deactivated": <timestamp|null>,
"catalog-timestamp": <timestamp>,
"facts-timestamp": <timestamp>,
"report-timestamp": <timestamp>,
"catalog-environment": <string>,
"facts-environment": <string>,
"report-environment": <string>}
"catalog_timestamp": <timestamp>,
"facts_timestamp": <timestamp>,
"report_timestamp": <timestamp>,
"catalog_environment": <string>,
"facts_environment": <string>,
"report_environment": <string>}
If a node of that certname doesn't exist, the response will instead be a hash of the form:
......
......@@ -13,7 +13,7 @@ can be used for paging results.
## URL Parameters for Paging Results
### `order-by`
### `order_by`
This parameter can be used to ask PuppetDB to return results sorted by one or more fields, in