You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2015/08/03 23:19:05 UTC
[9/9] incubator-usergrid git commit: Converted counters & events
pages to Markdown.
Converted counters & events pages to Markdown.
Project: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/commit/e17b4888
Tree: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/tree/e17b4888
Diff: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/diff/e17b4888
Branch: refs/heads/ug2-doc-update
Commit: e17b48889e38a7bc39dd8a37267e65a725f314e6
Parents: 840c4a0
Author: Dave Johnson <sn...@apache.org>
Authored: Mon Aug 3 17:18:40 2015 -0400
Committer: Dave Johnson <sn...@apache.org>
Committed: Mon Aug 3 17:18:40 2015 -0400
----------------------------------------------------------------------
.../creating-and-incrementing-counters.md | 74 +++++
docs/counters-and-events/events-and-counters.md | 272 +------------------
docs/counters-and-events/retrieving-counters.md | 109 ++++++++
docs/counters-and-events/tbd.md | 1 -
docs/index.rst | 4 +-
5 files changed, 192 insertions(+), 268 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/e17b4888/docs/counters-and-events/creating-and-incrementing-counters.md
----------------------------------------------------------------------
diff --git a/docs/counters-and-events/creating-and-incrementing-counters.md b/docs/counters-and-events/creating-and-incrementing-counters.md
new file mode 100644
index 0000000..3bf7f57
--- /dev/null
+++ b/docs/counters-and-events/creating-and-incrementing-counters.md
@@ -0,0 +1,74 @@
+## Creating & incrementing counters
+To create a new counter or increment an existing counter, include the counter property in the body of a POST to the /events endpoint. More than one counter can be incremented in the same request.
+
+__Note__: It may take up to 30 seconds after an event has been posted for the counter to be incremented.
+
+### Request syntax
+
+ curl -X POST https://api.usergrid.com/<org>/<app>/events -d '{"timestamp":<timestamp>, "counters" : {<counter_name>:<increment_value>}}'
+
+Parameters
+
+Parameter Description
+--------- -----------
+org Organization UUID or organization name
+app Application UUID or application name
+timestamp A required UNIX timestamp that specifies the time the counter is being incremented.
+counter_name The name of the counter to create or the existing counter to increment.
+increment_value The value to increment the counter by.
+
+Regarding the ``increment_value``, a negative number can be specified to decrement the value. A value of '0' can be specified to reset the value of the counter.
+
+For the ``timestamp``, specifying a value of 0 will automatically assign the current time.
+
+### Example request
+The following request will increment the 'button_clicks' counter by one, with a timestamp of the current time.
+
+ curl -X POST https://api.usergrid.com/your-org/your-app/events -d '{"timestamp":0, "counters" : {"button_clicks":1}}'
+
+### Example response
+
+ {
+ "action" : "post",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : { },
+ "path" : "/events",
+ "uri" : "https://api.usergrid.com/your-org/your-app/events",
+ "entities" : [ {
+ "uuid" : "b11217fc-9d3a-1427-b24e-699740088e05",
+ "type" : "event",
+ "created" : 1401224590293,
+ "modified" : 1401224590293,
+ "timestamp" : 1401224590293,
+ "counters" : {
+ "button_clicks" : 1
+ },
+ "message" : null,
+ "metadata" : {
+ "path" : "/events/b11217fc-9d3a-1427-b24e-699740088e05"
+ }
+ } ],
+ "timestamp" : 1401224590291,
+ "duration" : 30,
+ "organization" : "your-org",
+ "applicationName" : "your-app"
+ }
+
+## Decrementing/resetting counters
+To decrement a counter, specify a negative number for the counter value in any of the above examples.
+
+To reset a counter, specify a value of 0 for the counter value in any of the above examples.
+
+Note that the Usergrid JavaScript SDK also provides dedicated methods for decrementing and resetting counters.
+
+## Using counters hierarchically
+
+You can organize counters into hierarchies by giving them dot-separated names, e.g. ``button_clicks.homepage``. Incrementing a counter lower in a hierarchy increments all of the counters upward in the hierarchy chain.
+
+For example, you want to log errors that your app generates, so you create hierarchical counters for each module and function within that module. In this example, you create the following set of counters:
+
+ errors
+ errors.module
+ errors.module.function
+
+Incrementing ``errors.module.function`` by 1 increments all three counters by 1. A hierarchy can be a useful way of easily tracking actions in your app at both a cumulative and granular level.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/e17b4888/docs/counters-and-events/events-and-counters.md
----------------------------------------------------------------------
diff --git a/docs/counters-and-events/events-and-counters.md b/docs/counters-and-events/events-and-counters.md
index 1d6cdcd..cbb0b93 100644
--- a/docs/counters-and-events/events-and-counters.md
+++ b/docs/counters-and-events/events-and-counters.md
@@ -1,268 +1,8 @@
-# Events and counters
+# Counters & events
+Counters can be used to track statistics on many aspects of an application by keeping a running count of the number of times an action occurs in your app. Posting an event increments the counter. Counters can also be retrieved by time period, allowing you to generate reports on specific actions in your app.
-Events are typically used for application logging. For example, they
-could be used to log error messages that a system administrator might
-review at a later time. The event mechanism is optimized to handle large
-numbers of events, so it is an ideal mechanism for logging in your
-application.
+With Usergrid, you can define your own counters. Some of the things that you might track with a user-defined counter are:
-You can link events to specific users, groups, or custom-defined
-categories. When created with these links, events offer a powerful tool
-for running highly targeted, custom reports.
-
-Events are also the primary way to store custom counter data for
-analytics. See Counters (below) for further details.
-
-
-Event properties
-----------------
-
-You can pass various system-defined properties for an event. For
-example, you can specify a user property, with a uuid as its value. This
-will link the event to the user and can be used to query against the
-events queue (see Categorization below). The same is true for the group
-property. Pass it with a uuid as the value and the event will be linked
-to the group. To include a uuid of a user or group, add the uuid to the
-request body, for example:
-
- POST https://api.usergrid.com/my-org/my-app/events {"timestamp":0, "category" : "advertising", "counters" : {"ad_clicks" : 5},"user" : "1234891-477d-11e1-b2bd-22005a1c4e22", "group" : "75577d891-347d-2231-b5bd-23400a1c4e22"}
-
-The response body would look something like this:
-
- {
- "action": "post",
- "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
- "params": {},
- "path": "/events",
- "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/events",
- "entities": [
- {
- "uuid": "ce07ea3c-68b5-11e1-a586-9227e40e3559",
- "user": "1234891-477d-11e1-b2bd-22005a1c4e22",
- "group": "75577d891-347d-2231-b5bd-23400a1c4e22",
- "type": "event",
- "created": 1331166585282,
- "modified": 1331166585282,
- "counters": {
- "ad_clicks": 5
- },
- "metadata": {
- "path": "/events/ce07ea3c-68b5-11e1-a586-9227e40e3559"
- },
- "timestamp": 1331166585282
- }
- ],
- "timestamp": 1331166585018,
- "duration": 919,
- "organization": "my-org",
- "applicationName": "my-app"
- }
-
-You can also create application-specific event properties in addition to
-these predefined properties. The system-defined properties are reserved.
-You cannot use these names to create other properties for an event
-entity. In addition the events name is reserved for the events
-collection — you can't use it to name another collection.
-
-The System-defined properties are as follows:
-
- Property Type Description
- ----------- -------- -------------------------------------------------------------------------------------------
- uuid UUID Event’s unique entity ID
- type String "event"
- created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation
- modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification
- timestamp long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of application event (mandatory)
- user UUID UUID of application user that posted the event
- group UUID UUID of application group that posted the event
- category string Category used for organizing similar events
- counters map Counter used for tracking number of similar events
- message string Message describing event
-
-### Categorizing events
-
-As mentioned previously, you can link an event to a user or a group using a standard [Relationship](/docs/relationships).
-This enables you to categorize and qualify event data for use in
-tracking and analysis. For example, linking events to users and groups,
-enables you to track how often people use a feature. Not only can you
-determine the total number of users that used the feature, but also
-which groups contain users that made the most use of the feature. Or,
-you could provide a location with the event, so you could see how often
-a feature was used by people in San Francisco versus Los Angeles.
-
-Counters
---------
-
-User-defined counters are used in conjunction with events to keep
-statistics on many aspects of an application. User-defined counters are
-JSON objects that are added to events when they are posted. The act of
-posting an event increments the counter. Once created, user-defined
-counters can be used to get reports.
-
-**Note:** It may take up to 30 seconds for a counter to be updated.
-
-### User-Defined Counters
-
-With Apache Usergrid, you can define your own counters. Some of the things
-that you might track with a user-defined counter are:
-
-- How many times people click on the help button in your application.
-- How many times your game is played each day.
-- How many times your banner ads are clicked each day.
-
-You can choose any name for a user-defined counter. For example, the
-counter for the help button might be named “help\_button” or
-“help\_button\_clicks”.
-
-To create a user-defined counter, you post to the events collection and
-specify the name and increment value of the counter in the request body.
-The increment value is the value that the counter is incremented by for
-each tracked event. An increment value of 1, means that the counter is
-increment by 1 for each tracked event. You could also specify a higher
-increment value, such as 15, which would increment the value by that
-number, or a negative number, which would decrement the value. You can
-also reset the value of the counter, by specifying an increment value of
-0.
-
-When a counter is incremented by an event, there will be a 20-30 second
-delay between when the event is posted and when the counter is
-incremented.
-
-As an example, here's how to create a user-defined counter named
-“button\_clicks” with an increment value of 1:
-
- POST https://api.usergrid.com/my-org/my-app/events {"counters" : {"button_clicks" : 1},"timestamp" : "0"}
-
-The response body would look something like this:
-
- {
- "action": "post",
- "path": "/events",
- "uri": "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/events",
- "entities": [
- {
- "uuid": "39d41c46-d8e4-11e0-bcc1-12313f0204bb",
- "type": "event",
- "timestamp": 1315353555546016,
- "category":"advertising",
- "counters": {
- "button_clicks": 1
- },
- "created": 1315353555546016,
- "modified": 1315353555546016,
- "metadata": {
- "path": "/events/39d41c46-d8e4-11e0-bcc1-12313f0204bb"
- }
- }
- ],
- "timestamp": 1315353555537,
- "duration": 110,
- "organization": "my-org",
- "applicationName": "my-app"
- }
-
-### Counter hierarchy
-
-Counters are hierarchical in their structure and in the way they are
-incremented. Each level of the hierarchy is separated by the dot “.”
-operator. The hierarchical structure can be useful if you want to store
-or view statistics in a hierarchical way. For example, suppose you want
-to log errors that your app generates. One way to do this, is to fire an
-event every time an error occurs, by creating a counter called “errors”.
-However, you can get more detail by adding additional parameters to the
-counter. Imagine that you want to track errors in a specific module and
-function within that module, say module\_1, function\_1, you could use a
-counter like this:
-
- errors.module_1.function_1
-
-And then for a different function in the same module:
-
- errors.module_1.function_2
-
-And then for a different function in a different module:
-
- errors.module_2.function_3
-
-If each of the preceding examples were called once, the resulting values
-would be:
-
- errors = 3
- errors.module_1 = 2
- errors.module_1.function_1 = 1
- errors.module_1.function_2 = 1
- errors.module_2 = 1
- errors.module_2.function_3 = 1
-
-This tells you that there were 3 errors in the application, with 2 of
-those errors in module\_1. You can then drill down further to see errors
-in specific functions.
-
-### Using counters in time series queries
-
-Knowing the value of a counter is useful. However, you often need to
-know how the value varies over time. Fortunately, the API provides a
-method for you to view this data over any time interval or level of
-granularity.
-
-For example, let’s say you’re incrementing a counter every time someone
-launches your application. You might be interested in which days of the
-week the application sees the most usage. Using the API, you can examine
-the counter over a set of weeks, with the data split into daily
-intervals. Using this information, you can see which are your peak days
-of usage. You can also view usage across a single day, so you can see if
-your application is used more in the mornings or the evenings. For
-business reporting, you may be more interested in monthly reporting.
-
-Note that the system is able to provide you with the report data as you
-need it. The data is maintained in real-time so it can be viewed
-instantly.
-
-### Retrieving counter data
-
-To retrieve counter data, you issue a GET request to the /counters
-endpoint. This is a special, built-in collection that gives you access
-to all the counters currently in the system. The API also provides a
-number of parameters that you can use to search for counter data, as
-follows:
-
- Parameter Type Description
- ------------- ------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- start\_time An [Epoch(Unix)](http://en.wikipedia.org/wiki/Unix_time) timestamp in milliseconds The beginning of the time period to search
- end\_time An [Epoch(Unix)](http://en.wikipedia.org/wiki/Unix_time) timestamp in milliseconds The end of the time period to search
- counter string The name of a specific counter to search. You can specify more than one counter in a query (for example, counter=counter1&counter=counter2...)
- resolution string The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days. Possible values are all, minute, five\_minutes, half\_hour, hour, six\_day, day, week, and month.
-
-For example, to retrieve a time range of values, with a granularity of
-"day", for a counter called "button\_clicks", the GET request would look
-like this:
-
- GET /my-org/my-app/counters?start_time=1315119600000&end_time=1315724400000&resolution=day&counter=button_clicks
-
-The response body would look something like this:
-
- {
- action: "get",
- uri: "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/counters",
- timestamp: 1315354369272,
- duration: 28,
- counters: [
- {
- name: "button_clicks",
- values: [
- {
- value: 2
- timestamp: 1315180800000
- },
- {
- value: 1
- timestamp: 1315267200000
- },
- {
- value: 1
- timestamp: 1315353600000
- }
- ]
- }
- ]
- }
+* How many times people click on the help button in your application.
+* How many times your game is played each day.
+* How many times your banner ads are clicked each day.
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/e17b4888/docs/counters-and-events/retrieving-counters.md
----------------------------------------------------------------------
diff --git a/docs/counters-and-events/retrieving-counters.md b/docs/counters-and-events/retrieving-counters.md
new file mode 100644
index 0000000..5210952
--- /dev/null
+++ b/docs/counters-and-events/retrieving-counters.md
@@ -0,0 +1,109 @@
+# Retrieving counters
+To retrieve a counter, do the following:
+
+## Request syntax
+
+ curl -X GET https://api.usergrid.com/counters?counter=<counter_name>
+
+Parameters
+
+Parameter Description
+--------- -----------
+counter_name The name of the counter to be retrieved.
+
+More than one counter can be retrieved with a single request by appending additional counter parameters to the request URI.
+
+## Example request
+
+ curl -X GET https://api.usergrid.com/my-org/my-app/counters?counter=button_clicks
+
+## Example response
+
+ {
+ "action" : "get",
+ "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+ "params" : {
+ "counter" : [ "button_clicks" ]
+ },
+ "uri" : "https://api.usergrid.com/your-org/your-app",
+ "entities" : [ ],
+ "timestamp" : 1401310084096,
+ "duration" : 21,
+ "organization" : "your-org",
+ "applicationName" : "your-app",
+ "count" : 0,
+ "counters" : [ {
+ "name" : "button_clicks",
+ "values" : [ {
+ "timestamp" : 1,
+ "value" : 9
+ } ]
+ } ]
+ }
+
+## Retrieving counters by time interval
+Knowing the value of a counter is useful; however, you often need to know how the value varies over time. Fortunately, the API provides a method for you to view this data over any time interval or level of granularity.
+
+For example, let’s say you’re incrementing a counter every time someone launches your application. You might be interested in which days of the week the application sees the most usage. Using the API, you can examine the counter over a set of weeks, with the data split into daily intervals. Using this information, you can see which are your peak days of usage. You can also view usage across a single day, so you can see if your application is used more in the mornings or the evenings.
+
+## Request syntax
+
+ curl -X GET https://api.usergrid.com/counters?start_time=<timestamp>&end_time=<timestamp>&resolution=<resolution>&counter=<counter_name>
+
+Parameters
+
+Parameter Description
+--------- -----------
+start_time The beginning of the time period to search
+end_time The end of the time period to search
+resolution The interval at which counters are displayed.
+counter_name The name of the counter to be retrieved.
+
+The following resolutions are supported:
+
+* all
+* minute
+* five_minutes
+* half_hour
+* hour
+* six_day
+* day
+* week
+* month
+
+For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.
+
+## Example request
+
+For example, to retrieve a time range of values, with a granularity of "day", for a counter called "button_clicks", the GET request would look like this:
+
+ curl -X GET https://api.usergrid.com/my-org/my-app/counters?start_time=1315119600000&end_time=1315724400000&resolution=day&counter=button_clicks
+
+## Example response
+
+ {
+ action: "get",
+ uri: "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/counters",
+ timestamp: 1315354369272,
+ duration: 28,
+ counters: [
+ {
+ name: "button_clicks",
+ values: [
+ {
+ value: 2
+ timestamp: 1315180800000
+ },
+ {
+ value: 1
+ timestamp: 1315267200000
+ },
+ {
+ value: 1
+ timestamp: 1315353600000
+ }
+ ]
+ }
+ ]
+ }
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/e17b4888/docs/counters-and-events/tbd.md
----------------------------------------------------------------------
diff --git a/docs/counters-and-events/tbd.md b/docs/counters-and-events/tbd.md
deleted file mode 100644
index f65681d..0000000
--- a/docs/counters-and-events/tbd.md
+++ /dev/null
@@ -1 +0,0 @@
-# Coming soon...
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/e17b4888/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 6800aa4..5512b71 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -101,7 +101,9 @@ Apache Usergrid Documentation
:maxdepth: 2
:caption: Counters and Events
- counters-and-events/tbd
+ counters-and-events/events-and-counters
+ counters-and-events/creating-and-incrementing-counters
+ counters-and-events/retrieving-counters
.. _organization-and-application-management: