Repository Administration
Synapse Status and Maintenance Modes
A synapse stack can be in the following modes:
Mode | Accepted (200) | Unavailable (503) | Description |
|---|---|---|---|
READ_WRITE | GET, PUT, POST, & DELETE | none | This is the standard operating mode for Synapse. While in this mode all HTTP methods will be accepted (200s). |
READ_ONLY | GET | PUT, POST, & DELETE | While in this mode Synapse is read-only. While in this mode PUT, POST, and DELETE will all result in a 503 (Service Unavailable) response. |
DOWN | none | GET, PUT, POST, & DELETE | While in this mode Synapse will return 503 (Service Unavailable) for any non-administration call |
Note: Any 'reop/v1/admin/' will be accepted (200s) for any mode including READ_ONLY and DOWN. *
Getting the Current Stack Status
The following example shows how to get the current status. Note: This call does not require an authentication token.
Request
curl -i -k -H Accept:application/json -H Content-Type:application/json http://localhost:8080/services-repository-0.8-SNAPSHOT/repo/v1/admin/synapse/status
Response
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 10 Dec 2011 23:35:07 GMT
{
"status":"READ_WRITE",
"pendingMaintenanceMessage":"Synapse will be down for maintenance Saturday 12/10 from 11:58 to ll:59.",
"currentMessage":"Synapse is currently up and running."
}
There are two messages associated with the current status.
- currentMessage - This is the massage that is returned with any 503 (Service Unavailable) response. It is used to inform the caller of the current state. The administrator should set the message whenever the status changes.
- pendingMaintenanceMessage - This message shows pending maintenance information. This can be shown to end users to let them know of upcoming down time.
Updating the Current Status
Only an administrator can change the current status of Synapse. The administrator can set all three fields (status, currentMessage, and pendingMaintenanceMessage) with a single call:
Request
curl -i -k -H sessionToken:<your admin token> -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
"status": "DOWN",
"currentMessage": "Synapse is currently DOWN for maintenance. It will be back up in few minute.",
"pendingMaintenanceMessage":null,
}' http://localhost:8080/services-repository-0.8-SNAPSHOT/repo/v1/admin/synapse/status
Response
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 10 Dec 2011 23:47:18 GMT
{
"status":"DOWN",
"currentMessage":"Synapse is currently DOWN for maintenance. It will be back up in few minute."
}
StackStatus JSON Schema
{
"description":"The Status of the stack",
"properties":{
"status":{
"type":"string",
"description":"The status of this stack can be one of the following enumerations",
"name":"StatusEnum",
"id":"org.sagebionetworks.repo.model.status.StatusEnum",
"enum":[
"READ_WRITE",
"READ_ONLY",
"DOWN",
],
},
"currentMessage":{
"type":"string",
"description":"This message applies to the current state of the stack."
},
"pendingMaintenanceMessage":{
"type":"string",
"description":"This message is used to notify users of pending maintenance"
},
}
}
Storage Usage
Check the (external) storage usage by the Synapse system. You must be an administrator to perform these actions.
Get aggregated totals
Aggregated over any combination of dimensions listed in StorageUsageDimension (see StorageUsageDimension in Synapse Entity Types) except for USER_ID and ENTITY_ID which are provided via separate APIs. For example, the following command lists storage usage by content type and storage provider:
curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary?aggregation=CONTENT_TYPE,STORAGE_PROVIDER
Will get results like the following
{
"summaryList": [
{
"aggregatedCount": 181,
"aggregatedSize": 5409454583,
"dimensionList": [
{
"dimension": "CONTENT_TYPE",
"value": "application/binary"
},
{
"dimension": "STORAGE_PROVIDER",
"value": "awss3"
}
]
},
{
"aggregatedCount": 9,
"aggregatedSize": 0,
"dimensionList": [
{
"dimension": "CONTENT_TYPE",
"value": "application/binary"
},
{
"dimension": "STORAGE_PROVIDER",
"value": "external"
}
]
},
{
"aggregatedCount": 3,
"aggregatedSize": 195333619,
"dimensionList": [
{
"dimension": "CONTENT_TYPE",
"value": "application/octet-stream"
},
{
"dimension": "STORAGE_PROVIDER",
"value": "awss3"
}
]
},
{
"aggregatedCount": 3590,
"aggregatedSize": 0,
"dimensionList": [
{
"dimension": "CONTENT_TYPE",
"value": "application/octet-stream"
},
{
"dimension": "STORAGE_PROVIDER",
"value": "external"
}
]
},
{
"aggregatedCount": 19,
"aggregatedSize": 9927282,
"dimensionList": [
{
"dimension": "CONTENT_TYPE",
"value": "application/pdf"
},
{
"dimension": "STORAGE_PROVIDER",
"value": "awss3"
}
]
},
{
"aggregatedCount": 8370,
"aggregatedSize": 0,
"dimensionList": [
{
"dimension": "CONTENT_TYPE",
"value": "application/x-tar"
},
{
"dimension": "STORAGE_PROVIDER",
"value": "external"
}
]
},
]
}
Without any aggregation, the same URL will get only the grand totals.
curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary
{
"totalCount":133827,
"totalSize":1080865415607,
"summaryList":[]
}
Get usage by users
Lists the aggregated usage by users in descending order of 'aggregatedSize':
curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary/perUser
Example response body listing the top 3 users:
{
"summaryList": [
{
"aggregatedCount": 35204,
"aggregatedSize": 283329626902,
"dimensionList": [
{
"dimension": "USER_ID",
"value": "273975"
}
]
},
{
"aggregatedCount": 458,
"aggregatedSize": 227459357704,
"dimensionList": [
{
"dimension": "USER_ID",
"value": "342024"
}
]
},
{
"aggregatedCount": 179,
"aggregatedSize": 66928683678,
"dimensionList": [
{
"dimension": "USER_ID",
"value": "274010"
}
]
},
...
]
}
Get usage by entities
Lists the aggregated usage by entities in descending order of 'aggregatedSize':
curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary/perEntity
Example response body listing the top 3 entities:
{
"summaryList": [
{
"aggregatedCount": 1,
"aggregatedSize": 5210220350,
"dimensionList": [
{
"dimension": "NODE_ID",
"value": "317475"
}
]
},
{
"aggregatedCount": 1,
"aggregatedSize": 4670860925,
"dimensionList": [
{
"dimension": "NODE_ID",
"value": "1113803"
}
]
},
{
"aggregatedCount": 2,
"aggregatedSize": 4235837739,
"dimensionList": [
{
"dimension": "NODE_ID",
"value": "4494"
}
]
},
...
]
}